HP HP-UX SNAplus2 R7 Reference Guide

HP-UX SNAplus2 R7 Administration Command

Reference

HP-UX 11i v1, 11i v2 and 11i v3

Edition: 4

Manufacturing Part Number: 5991–2742
April 2007

© 2007 Hewlett-Packard Development Company, L.P. All rights reserved.

Contents

Legal Notices.............................................................................................................................................24

Warranty............................................................................................................................................24

U.S. Government License.. ..............................................................................................................24

Copyright Notices.............................................................................................................................24

Trademark Notices............................................................................................................................24

Publishing History.....................................................................................................................................25

New and Changed Information in This Edition.. .............................................................................. 25

Before You Begin...................................................................................................................................... 26

Prerequisite Knowledge....................................................................................................................26

About This Book...............................................................................................................................26

Organization of This Book....................................................................................................... 26

Typographic Conventions.........................................................................................................26

SNAplus2 Publications.....................................................................................................................27

Publications for Users..............................................................................................................27

Publications for Administrators.. .............................................................................................. 28

Publications for Programmers..................................................................................................28

Related Publications.........................................................................................................................29

Chapter 1 Introduction to SNAplus2 Administration Commands.. .................................................. 30

1.1 Using snapadmin.. .................................................................................................................. 31

1.1.1 Command Line Options...............................................................................................31

1.1.2 Parameter Syntax Used for Administration Commands..............................................33

1.1.3 Examples of Administration Commands.....................................................................37

Chapter 2 Administration Commands.. ............................................................................................... 38

2.1 activate_session......................................................................................................................38

2.1.1 Supplied Parameters.. ................................................................................................. 38

2.1.2 Returned Parameters..................................................................................................39

2.1.3 Error Return Codes.. ...................................................................................................39

2.2 add_backup.............................................................................................................................40

2.2.1 Supplied Parameters.. ................................................................................................. 40

2.2.2 Returned Parameters..................................................................................................41

2.2.3 Error Return Codes.. ...................................................................................................41

2.3 add_dlc_trace..........................................................................................................................41

2.3.1 Supplied Parameters.. ................................................................................................. 42

2.3.2 Returned Parameters..................................................................................................43

2.3.3 Error Return Codes.. ...................................................................................................43

ii

2.4 aping........................................................................................................................................44

2.4.1 Supplied Parameters.. ................................................................................................. 44

2.4.2 Returned Parameters..................................................................................................46

2.4.3 Error Return Codes.. ...................................................................................................47

2.5 change_session_limit..............................................................................................................49

2.5.1 Supplied Parameters.. ................................................................................................. 49

2.5.2 Returned Parameters..................................................................................................50

2.5.3 Error Return Codes.. ...................................................................................................51

2.6 deactivate_conv_group............................................................................................................52

2.6.1 Supplied Parameters.. ................................................................................................. 52

2.6.2 Returned Parameters..................................................................................................53

2.6.3 Error Return Codes.. ...................................................................................................53

2.7 deactivate_lu_0_to_3..............................................................................................................54

2.7.1 Supplied Parameters.. ................................................................................................. 54

2.7.2 Returned Parameters..................................................................................................54

2.7.3 Error Return Codes.. ...................................................................................................54

2.8 deactivate_session..................................................................................................................55

2.8.1 Supplied Parameters.. ................................................................................................. 55

2.8.2 Returned Parameters..................................................................................................56

2.8.3 Error Return Codes.. ...................................................................................................56

2.9 define_3270_diag....................................................................................................................57

2.9.1 Supplied Parameters.. ................................................................................................. 57

2.9.2 Returned Parameters..................................................................................................59

2.9.3 Error Return Codes.. ...................................................................................................59

2.10 define_adjacent_len_node....................................................................................................59

2.10.1 Supplied Parameters.. ............................................................................................... 60

2.10.2 Returned Parameters................................................................................................ 60

2.10.3 Error Return Codes.. .................................................................................................60

2.11 define_cn...............................................................................................................................61

2.11.1 Supplied Parameters.. ............................................................................................... 61

2.11.2 Returned Parameters................................................................................................ 63

2.11.3 Error Return Codes.. .................................................................................................63

2.12 define_cos.............................................................................................................................64

2.12.1 Supplied Parameters.. ............................................................................................... 64

2.12.2 Returned Parameters................................................................................................ 69

2.12.3 Error Return Codes.. .................................................................................................69

2.13 define_cpic_side_info.. .......................................................................................................... 70

2.13.1 Supplied Parameters.. ............................................................................................... 70

2.13.2 Returned Parameters................................................................................................ 71

2.13.3 Error Return Codes.. .................................................................................................71

2.14 define_default_pu..................................................................................................................72

2.14.1 Supplied Parameters.. ............................................................................................... 72

2.14.2 Returned Parameters................................................................................................ 72

iii

2.14.3 Error Return Codes.. .................................................................................................73

2.15 define_defaults...................................................................................................................... 73

2.15.1 Supplied Parameters.. ............................................................................................... 73

2.15.2 Returned Parameters................................................................................................ 74

2.15.3 Error Return Codes.. .................................................................................................74

2.16 define_directory_entry...........................................................................................................74

2.16.1 Supplied Parameters.. ............................................................................................... 75

2.16.2 Returned Parameters................................................................................................ 76

2.16.3 Error Return Codes.. .................................................................................................76

2.17 define_dlur_defaults.............................................................................................................. 77

2.17.1 Supplied Parameters.. ............................................................................................... 77

2.17.2 Returned Parameters................................................................................................ 78

2.17.3 Error Return Codes.. .................................................................................................78

2.18 define_domain_config_file.....................................................................................................79

2.18.1 Supplied Parameters.. ............................................................................................... 79

2.18.2 Returned Parameters................................................................................................ 79

2.18.3 Error Return Codes.. .................................................................................................79

2.19 define_downstream_lu..........................................................................................................79

2.19.1 Supplied Parameters.. ............................................................................................... 80

2.19.2 Returned Parameters................................................................................................ 81

2.19.3 Error Return Codes.. .................................................................................................81

2.20 define_downstream_lu_range............................................................................................... 82

2.20.1 Supplied Parameters.. ............................................................................................... 83

2.20.2 Returned Parameters................................................................................................ 84

2.20.3 Error Return Codes.. .................................................................................................84

2.21 define_dspu_template...........................................................................................................85

2.21.1 Supplied Parameters.. ............................................................................................... 86

2.21.2 Returned Parameters................................................................................................ 87

2.21.3 Error Return Codes.. .................................................................................................87

2.22 define_emulator_user............................................................................................................88

2.22.1 Supplied Parameters.. ............................................................................................... 88

2.22.2 Returned Parameters................................................................................................ 92

2.22.3 Error Return Codes.. .................................................................................................93

2.23 define_ethernet_dlc...............................................................................................................93

2.24 define_ethernet_ls.................................................................................................................93

2.25 define_ethernet_port.............................................................................................................93

2.26 define_fddi_dlc......................................................................................................................93

2.27 define_fddi_ls........................................................................................................................93

2.28 define_fddi_port.. .................................................................................................................. 94

2.29 define_focal_point.................................................................................................................94

2.29.1 Supplied Parameters.. ............................................................................................... 94

iv

2.29.2 Returned Parameters................................................................................................ 95

2.29.3 Error Return Codes.. .................................................................................................95

2.30 define_internal_pu.................................................................................................................96

2.30.1 Supplied Parameters.. ............................................................................................... 96

2.30.2 Returned Parameters................................................................................................ 98

2.30.3 Error Return Codes.. .................................................................................................98

2.31 define_ip_dlc.........................................................................................................................99

2.31.1 Supplied Parameters.. ............................................................................................... 99

2.31.2 Returned Parameters.............................................................................................. 100

2.31.3 Error Return Codes.. ............................................................................................... 100

2.32 define_ip_ls.........................................................................................................................101

2.32.1 Supplied Parameters.. ............................................................................................. 101

2.32.2 Returned Parameters.............................................................................................. 109

2.32.3 Error Return Codes.. ............................................................................................... 109

2.33 define_ip_port.. ................................................................................................................... 111

2.33.1 Supplied Parameters.. ............................................................................................. 111

2.33.2 Returned Parameters.............................................................................................. 115

2.33.3 Error Return Codes.. ............................................................................................... 115

2.33.4 Incoming Calls.........................................................................................................116

2.34 define_local_lu.................................................................................................................... 116

2.34.1 Supplied Parameters.. ............................................................................................. 116

2.34.2 Returned Parameters.............................................................................................. 119

2.34.3 Error Return Codes.. ............................................................................................... 119

2.35 define_ls_routing.................................................................................................................120

2.35.1 Supplied Parameters.. ............................................................................................. 120

2.35.2 Returned Parameters.............................................................................................. 121

2.35.3 Error Return Codes.. ............................................................................................... 121

2.36 define_lu_0_to_3.................................................................................................................122

2.36.1 Supplied Parameters.. ............................................................................................. 122

2.36.2 Returned Parameters.............................................................................................. 124

2.36.3 Error Return Codes.. ............................................................................................... 124

2.37 define_lu_0_to_3_range......................................................................................................125

2.37.1 Supplied Parameters.. ............................................................................................. 126

2.37.2 Returned Parameters.............................................................................................. 128

2.37.3 Error Return Codes.. ............................................................................................... 128

2.38 define_lu_lu_password........................................................................................................130

2.38.1 Supplied Parameters.. ............................................................................................. 130

2.38.2 Returned Parameters.............................................................................................. 131

2.38.3 Error Return Codes.. ............................................................................................... 131

2.39 define_lu_pool.....................................................................................................................131

2.39.1 Supplied Parameters.. ............................................................................................. 131

2.39.2 Returned Parameters.............................................................................................. 132

2.39.3 Error Return Codes.. ............................................................................................... 132

v

2.40 define_lu62_timeout............................................................................................................133

2.40.1 Supplied Parameters.. ............................................................................................. 133

2.40.2 Returned Parameters.............................................................................................. 134

2.40.3 Error Return Codes.. ............................................................................................... 134

2.41 define_mode........................................................................................................................134

2.41.1 Supplied Parameters.. ............................................................................................. 135

2.41.2 Returned Parameters.............................................................................................. 137

2.41.3 Error Return Codes.. ............................................................................................... 137

2.42 define_node.........................................................................................................................138

2.42.1 Supplied Parameters.. ............................................................................................. 138

2.42.2 Returned Parameters.............................................................................................. 145

2.42.3 Error Return Codes.. ............................................................................................... 146

2.43 define_partner_lu.. .............................................................................................................. 147

2.43.1 Supplied Parameters.. ............................................................................................. 147

2.43.2 Returned Parameters.............................................................................................. 148

2.43.3 Error Return Codes.. ............................................................................................... 148

2.44 define_qllc_dlc.....................................................................................................................149

2.44.1 Supplied Parameters.. ............................................................................................. 149

2.44.2 Returned Parameters.............................................................................................. 150

2.44.3 Error Return Codes.. ............................................................................................... 150

2.45 define_qllc_ls.......................................................................................................................150

2.45.1 Supplied Parameters.. ............................................................................................. 151

2.45.2 Returned Parameters.............................................................................................. 164

2.45.3 Error Return Codes.. ............................................................................................... 164

2.46 define_qllc_port...................................................................................................................167

2.46.1 Supplied Parameters.. ............................................................................................. 167

2.46.2 Returned Parameters.............................................................................................. 172

2.46.3 Error Return Codes.. ............................................................................................... 172

2.46.4 Incoming Calls.........................................................................................................173

2.47 define_rcf_access............................................................................................................... 174

2.47.1 Supplied Parameters.. ............................................................................................. 174

2.47.2 Returned Parameters.............................................................................................. 175

2.47.3 Error Return Codes.. ............................................................................................... 175

2.48 define_rje_wkstn.. ............................................................................................................... 175

2.48.1 Supplied Parameters.. ............................................................................................. 176

2.48.2 Returned Parameters.............................................................................................. 177

2.48.3 Error Return Codes.. ............................................................................................... 177

2.49 define_rtp_tuning.. .............................................................................................................. 177

2.49.1 Supplied Parameters.. ............................................................................................. 177

2.49.2 Returned Parameters.............................................................................................. 178

2.49.3 Error Return Codes.. ............................................................................................... 178

2.50 define_sdlc_dlc....................................................................................................................179

2.50.1 Supplied Parameters.. ............................................................................................. 179

vi

2.50.2 Returned Parameters.............................................................................................. 180

2.50.3 Error Return Codes.. ............................................................................................... 180

2.51 define_sdlc_ls......................................................................................................................181

2.51.1 Supplied Parameters.. ............................................................................................. 181

2.51.2 Returned Parameters.............................................................................................. 195

2.51.3 Error Return Codes.. ............................................................................................... 195

2.51.4 Modem Control Characters..................................................................................... 198

2.52 define_sdlc_port..................................................................................................................199

2.52.1 Supplied Parameters.. ............................................................................................. 199

2.52.2 Returned Parameters.............................................................................................. 208

2.52.3 Error Return Codes.. ............................................................................................... 209

2.52.4 Incoming Calls.........................................................................................................210

2.53 define_security_access_list.................................................................................................210

2.53.1 Supplied Parameters.. ............................................................................................. 210

2.53.2 Returned Parameters.............................................................................................. 211

2.53.3 Error Return Codes.. ............................................................................................... 211

2.54 define_tn3270_access........................................................................................................ 211

2.54.1 Supplied Parameters.. ............................................................................................. 212

2.54.2 Returned Parameters.............................................................................................. 214

2.54.3 Error Return Codes.. ............................................................................................... 214

2.54.4 Using the Telnet Daemon’s TCP/IP Port.................................................................215

2.55 define_tn3270_association..................................................................................................215

2.55.1 Supplied Parameters.. ............................................................................................. 215

2.55.2 Returned Parameters.............................................................................................. 216

2.55.3 Error Return Codes.. ............................................................................................... 216

2.56 define_tn3270_defaults....................................................................................................... 216

2.56.1 Supplied Parameters.. ............................................................................................. 217

2.56.2 Returned Parameters.............................................................................................. 217

2.56.3 Error Return Codes.. ............................................................................................... 218

2.57 define_tp..............................................................................................................................218

2.57.1 Supplied Parameters.. ............................................................................................. 218

2.57.2 Returned Parameters.............................................................................................. 220

2.57.3 Error Return Codes.. ............................................................................................... 220

2.58 define_tp_load_info.. ...........................................................................................................221

2.58.1 Supplied Parameters.. ............................................................................................. 221

2.58.2 Returned Parameters.............................................................................................. 222

2.58.3 Error Return Codes.. ............................................................................................... 222

2.59 define_tr_dlc, define_ethernet_dlc, define_fddi_dlc............................................................223

2.59.1 Supplied Parameters.. ............................................................................................. 223

2.59.2 Returned Parameters.............................................................................................. 224

2.59.3 Error Return Codes.. ............................................................................................... 224

2.60 define_tr_ls, define_ethernet_ls, define_fddi_ls..................................................................225

2.60.1 Supplied Parameters.. ............................................................................................. 225

vii

2.60.2 Returned Parameters.............................................................................................. 237

2.60.3 Error Return Codes.. ............................................................................................... 237

2.60.4 Bit Ordering in MAC Addresses..............................................................................239

2.61 define_tr_port, define_ethernet_port, define_fddi_port......................................................240

2.61.1 Supplied Parameters.. ............................................................................................. 241

2.61.2 Returned Parameters.............................................................................................. 245

2.61.3 Error Return Codes.. ............................................................................................... 245

2.61.4 Incoming Calls.........................................................................................................246

2.62 define_userid_password.. ................................................................................................... 247

2.62.1 Supplied Parameters.. ............................................................................................. 247

2.62.2 Returned Parameters.............................................................................................. 248

2.62.3 Error Return Codes.. ............................................................................................... 248

2.63 delete_adjacent_len_node..................................................................................................248

2.63.1 Supplied Parameters.. ............................................................................................. 249

2.63.2 Returned Parameters.............................................................................................. 249

2.63.3 Error Return Codes.. ............................................................................................... 249

2.64 delete_backup..................................................................................................................... 250

2.64.1 Supplied Parameters.. ............................................................................................. 250

2.64.2 Returned Parameters.............................................................................................. 250

2.64.3 Error Return Codes.. ............................................................................................... 251

2.65 delete_cn.............................................................................................................................251

2.65.1 Supplied Parameters.. ............................................................................................. 251

2.65.2 Returned Parameters.............................................................................................. 252

2.65.3 Error Return Codes.. ............................................................................................... 252

2.66 delete_cos...........................................................................................................................252

2.66.1 Supplied Parameters.. ............................................................................................. 253

2.66.2 Returned Parameters.............................................................................................. 253

2.66.3 Error Return Codes.. ............................................................................................... 253

2.67 delete_cpic_side_info.. ........................................................................................................ 253

2.67.1 Supplied Parameters.. ............................................................................................. 254

2.67.2 Returned Parameters.............................................................................................. 254

2.67.3 Error Return Codes.. ............................................................................................... 254

2.68 delete_directory_entry.........................................................................................................254

2.68.1 Supplied Parameters.. ............................................................................................. 255

2.68.2 Returned Parameters.............................................................................................. 255

2.68.3 Error Return Codes.. ............................................................................................... 255

2.69 delete_dlc............................................................................................................................256

2.69.1 Supplied Parameters.. ............................................................................................. 256

2.69.2 Returned Parameters.............................................................................................. 256

2.69.3 Error Return Codes.. ............................................................................................... 256

viii

2.70 delete_downstream_lu........................................................................................................257

2.70.1 Supplied Parameters.. ............................................................................................. 257

2.70.2 Returned Parameters.............................................................................................. 257

2.70.3 Error Return Codes.. ............................................................................................... 257

2.71 delete_downstream_lu_range............................................................................................. 258

2.71.1 Supplied Parameters.. ............................................................................................. 258

2.71.2 Returned Parameters.............................................................................................. 259

2.71.3 Error Return Codes.. ............................................................................................... 259

2.72 delete_dspu_template.........................................................................................................259

2.72.1 Supplied Parameters.. ............................................................................................. 259

2.72.2 Returned Parameters.............................................................................................. 260

2.72.3 Error Return Codes.. ............................................................................................... 261

2.73 delete_emulator_user..........................................................................................................261

2.73.1 Supplied Parameters.. ............................................................................................. 261

2.73.2 Returned Parameters.............................................................................................. 262

2.73.3 Error Return Codes.. ............................................................................................... 262

2.74 delete_focal_point...............................................................................................................263

2.74.1 Supplied Parameters.. ............................................................................................. 263

2.74.2 Returned Parameters.............................................................................................. 263

2.74.3 Error Return Codes.. ............................................................................................... 263

2.75 delete_internal_pu...............................................................................................................264

2.75.1 Supplied Parameters.. ............................................................................................. 264

2.75.2 Returned Parameters.............................................................................................. 264

2.75.3 Error Return Codes.. ............................................................................................... 265

2.76 delete_local_lu.................................................................................................................... 265

2.76.1 Supplied Parameters.. ............................................................................................. 266

2.76.2 Returned Parameters.............................................................................................. 266

2.76.3 Error Return Codes.. ............................................................................................... 266

2.77 delete_ls..............................................................................................................................266

2.77.1 Supplied Parameters.. ............................................................................................. 266

2.77.2 Returned Parameters.............................................................................................. 267

2.77.3 Error Return Codes.. ............................................................................................... 267

2.78 delete_ls_routing.................................................................................................................267

2.78.1 Supplied Parameters.. ............................................................................................. 268

2.78.2 Returned Parameters.............................................................................................. 268

2.78.3 Error Return Codes.. ............................................................................................... 268

2.79 delete_lu_0_to_3.................................................................................................................269

2.79.1 Supplied Parameters.. ............................................................................................. 269

2.79.2 Returned Parameters.............................................................................................. 269

2.79.3 Error Return Codes.. ............................................................................................... 270

2.80 delete_lu_0_to_3_range......................................................................................................270

2.80.1 Supplied Parameters.. ............................................................................................. 270

2.80.2 Returned Parameters.............................................................................................. 271

2.80.3 Error Return Codes.. ............................................................................................... 271

2.81 delete_lu_lu_password........................................................................................................272

ix

2.81.1 Supplied Parameters.. ............................................................................................. 272

2.81.2 Returned Parameters.............................................................................................. 272

2.81.3 Error Return Codes.. ............................................................................................... 273

2.82 delete_lu_pool.....................................................................................................................273

2.82.1 Supplied Parameters.. ............................................................................................. 273

2.82.2 Returned Parameters.............................................................................................. 274

2.82.3 Error Return Codes.. ............................................................................................... 274

2.83 delete_lu62_timeout............................................................................................................274

2.83.1 Supplied Parameters.. ............................................................................................. 274

2.83.2 Returned Parameters.............................................................................................. 275

2.83.3 Error Return Codes.. ............................................................................................... 275

2.84 delete_mode........................................................................................................................276

2.84.1 Supplied Parameters.. ............................................................................................. 276

2.84.2 Returned Parameters.............................................................................................. 276

2.84.3 Error Return Codes.. ............................................................................................... 276

2.85 delete_partner_lu.. .............................................................................................................. 277

2.85.1 Supplied Parameters.. ............................................................................................. 277

2.85.2 Returned Parameters.............................................................................................. 277

2.85.3 Error Return Codes.. ............................................................................................... 278

2.86 delete_port.. ........................................................................................................................ 278

2.86.1 Supplied Parameters.. ............................................................................................. 278

2.86.2 Returned Parameters.............................................................................................. 278

2.86.3 Error Return Codes.. ............................................................................................... 278

2.87 delete_rcf_access............................................................................................................... 279

2.87.1 Supplied Parameters.. ............................................................................................. 279

2.87.2 Returned Parameters.............................................................................................. 279

2.87.3 Error Return Codes.. ............................................................................................... 279

2.88 delete_rje_wkstn.. ............................................................................................................... 280

2.88.1 Supplied Parameters.. ............................................................................................. 280

2.88.2 Returned Parameters.............................................................................................. 280

2.88.3 Error Return Codes.. ............................................................................................... 280

2.89 delete_security_access_list.................................................................................................281

2.89.1 Supplied Parameters.. ............................................................................................. 281

2.89.2 Returned Parameters.............................................................................................. 281

2.89.3 Error Return Codes.. ............................................................................................... 281

2.90 delete_tn3270_access........................................................................................................ 282

2.90.1 Supplied Parameters.. ............................................................................................. 282

2.90.2 Returned Parameters.............................................................................................. 283

2.90.3 Error Return Codes.. ............................................................................................... 283

2.91 delete_tn3270_association..................................................................................................284

2.91.1 Supplied Parameters.. ............................................................................................. 284

2.91.2 Returned Parameters.............................................................................................. 284

2.91.3 Error Return Codes.. ............................................................................................... 284

x

2.92 delete_tp..............................................................................................................................285

2.92.1 Supplied Parameters.. ............................................................................................. 285

2.92.2 Returned Parameters.............................................................................................. 285

2.92.3 Error Return Codes.. ............................................................................................... 285

2.93 delete_tp_load_info.. ...........................................................................................................286

2.93.1 Supplied Parameters.. ............................................................................................. 286

2.93.2 Returned Parameters.............................................................................................. 286

2.93.3 Error Return Codes.. ............................................................................................... 286

2.94 delete_userid_password.. ................................................................................................... 287

2.94.1 Supplied Parameters.. ............................................................................................. 287

2.94.2 Returned Parameters.............................................................................................. 287

2.94.3 Error Return Codes.. ............................................................................................... 287

2.95 init_node..............................................................................................................................288

2.95.1 Supplied Parameters.. ............................................................................................. 288

2.95.2 Returned Parameters.............................................................................................. 288

2.95.3 Error Return Codes.. ............................................................................................... 288

2.96 initialize_session_limit.........................................................................................................289

2.96.1 Supplied Parameters.. ............................................................................................. 289

2.96.2 Returned Parameters.............................................................................................. 291

2.96.3 Error Return Codes.. ............................................................................................... 291

2.97 path_switch.. ....................................................................................................................... 293

2.97.1 Supplied Parameters.. ............................................................................................. 293

2.97.2 Returned Parameters.............................................................................................. 293

2.97.3 Error Return Codes.. ............................................................................................... 293

2.98 query_3270_diag.. .............................................................................................................. 294

2.98.1 Supplied Parameters.. ............................................................................................. 294

2.98.2 Returned Parameters.............................................................................................. 295

2.98.3 Error Return Codes.. ............................................................................................... 295

2.99 query_3270_user................................................................................................................ 296

2.99.1 Supplied Parameters.. ............................................................................................. 296

2.99.2 Returned Parameters: Summary Information.........................................................298

2.99.3 Returned Parameters: Detailed Information........................................................... 298

2.99.4 Error Return Codes.. ............................................................................................... 299

2.100 query_3270_user_sessions.. ............................................................................................ 299

2.100.1 Supplied Parameters.. ........................................................................................... 300

2.100.2 Returned Parameters: Summary Information.......................................................301

2.100.3 Returned Parameters: Detailed Information......................................................... 301

2.100.4 Error Return Codes.. ............................................................................................. 301

2.101 query_active_transaction.................................................................................................. 302

2.101.1 Supplied Parameters.. ........................................................................................... 302

2.101.2 Returned Parameters............................................................................................ 303

2.101.3 Error Return Codes.. ............................................................................................. 304

2.102 query_adjacent_nn............................................................................................................305

xi

2.102.1 Supplied Parameters.. ........................................................................................... 305

2.102.2 Returned Parameters............................................................................................ 305

2.102.3 Error Return Codes.. ............................................................................................. 306

2.103 query_available_tp.. .......................................................................................................... 307

2.103.1 Supplied Parameters.. ........................................................................................... 307

2.103.2 Returned Parameters............................................................................................ 308

2.103.3 Error Return Codes.. ............................................................................................. 308

2.104 query_bck_cs_trace..........................................................................................................309

2.104.1 Supplied Parameters.. ........................................................................................... 309

2.104.2 Returned Parameters............................................................................................ 309

2.104.3 Error Return Codes.. ............................................................................................. 309

2.105 query_buffer_availability.................................................................................................... 310

2.105.1 Supplied Parameters.. ........................................................................................... 310

2.105.2 Returned Parameters............................................................................................ 310

2.105.3 Error Return Codes.. ............................................................................................. 312

2.106 query_central_logger.........................................................................................................312

2.106.1 Supplied Parameters.. ........................................................................................... 313

2.106.2 Returned Parameters............................................................................................ 313

2.106.3 Error Return Codes.. ............................................................................................. 313

2.107 query_central_logging.......................................................................................................313

2.107.1 Supplied Parameters.. ........................................................................................... 313

2.107.2 Returned Parameters............................................................................................ 314

2.107.3 Error Return Codes.. ............................................................................................. 314

2.108 query_cn.. .........................................................................................................................314

2.108.1 Supplied Parameters.. ........................................................................................... 315

2.108.2 Returned Parameters............................................................................................ 315

2.108.3 Error Return Codes.. ............................................................................................. 317

2.109 query_cn_port................................................................................................................... 317

2.109.1 Supplied Parameters.. ........................................................................................... 318

2.109.2 Returned Parameters............................................................................................ 318

2.109.3 Error Return Codes.. ............................................................................................. 319

2.110 query_conversation...........................................................................................................319

2.110.1 Supplied Parameters.. ........................................................................................... 319

2.110.2 Returned Parameters............................................................................................ 320

2.110.3 Error Return Codes.. ............................................................................................. 321

2.111 query_cos..........................................................................................................................322

2.111.1 Supplied Parameters.. ........................................................................................... 322

2.111.2 Returned Parameters............................................................................................ 323

2.111.3 Error Return Codes.. ............................................................................................. 324

2.112 query_cos_node_row........................................................................................................ 324

2.112.1 Supplied Parameters.. ........................................................................................... 324

2.112.2 Returned Parameters............................................................................................ 325

2.112.3 Error Return Codes.. ............................................................................................. 326

xii

2.113 query_cos_tg_row............................................................................................................. 326

2.113.1 Supplied Parameters.. ........................................................................................... 326

2.113.2 Returned Parameters............................................................................................ 327

2.113.3 Error Return Codes.. ............................................................................................. 330

2.114 query_cpic_side_info.........................................................................................................330

2.114.1 Supplied Parameters.. ........................................................................................... 330

2.114.2 Returned Parameters............................................................................................ 331

2.114.3 Error Return Codes.. ............................................................................................. 332

2.115 query_cs_trace..................................................................................................................332

2.115.1 Supplied Parameters.. ........................................................................................... 332

2.115.2 Returned Parameters............................................................................................ 333

2.115.3 Error Return Codes.. ............................................................................................. 333

2.116 query_default_pu...............................................................................................................334

2.116.1 Supplied Parameters.. ........................................................................................... 334

2.116.2 Returned Parameters............................................................................................ 334

2.116.3 Error Return Codes.. ............................................................................................. 335

2.117 query_defaults...................................................................................................................335

2.117.1 Supplied Parameters.. ........................................................................................... 335

2.117.2 Returned Parameters............................................................................................ 335

2.117.3 Error Return Codes.. ............................................................................................. 336

2.118 query_directory_entry........................................................................................................336

2.118.1 Supplied Parameters.. ........................................................................................... 337

2.118.2 Returned Parameters: Summary Information.......................................................339

2.118.3 Returned Parameters: Detailed Information......................................................... 339

2.118.4 Error Return Codes.. ............................................................................................. 342

2.119 query_directory_lu.............................................................................................................342

2.119.1 Supplied Parameters.. ........................................................................................... 342

2.119.2 Returned Parameters: Summary Information.......................................................343

2.119.3 Returned Parameters: Detailed Information......................................................... 343

2.119.4 Error Return Codes.. ............................................................................................. 345

2.120 query_directory_stats........................................................................................................345

2.120.1 Supplied Parameters.. ........................................................................................... 345

2.120.2 Returned Parameters............................................................................................ 346

2.120.3 Error Return Codes.. ............................................................................................. 347

2.121 query_dlc...........................................................................................................................347

2.121.1 Supplied Parameters.. ........................................................................................... 347

2.121.2 Returned Parameters: Summary Information.......................................................348

2.121.3 Returned Parameters: Detailed Information......................................................... 349

2.121.4 Error Return Codes.. ............................................................................................. 351

2.122 query_dlc_trace.................................................................................................................351

2.122.1 Supplied Parameters.. ........................................................................................... 351

2.122.2 Returned Parameters............................................................................................ 353

2.122.3 Error Return Codes.. ............................................................................................. 355

xiii

2.123 query_dlur_defaults...........................................................................................................356

2.123.1 Supplied Parameters.. ........................................................................................... 356

2.123.2 Returned Parameters............................................................................................ 356

2.123.3 Error Return Codes.. ............................................................................................. 357

2.124 query_dlur_lu.. ..................................................................................................................357

2.124.1 Supplied Parameters.. ........................................................................................... 357

2.124.2 Returned Parameters: Summary Information.......................................................358

2.124.3 Returned Parameters: Detailed Information......................................................... 359

2.124.4 Error Return Codes.. ............................................................................................. 359

2.125 query_dlur_pu................................................................................................................... 360

2.125.1 Supplied Parameters.. ........................................................................................... 360

2.125.2 Returned Parameters: Summary Information.......................................................362

2.125.3 Returned Parameters: Detailed Information......................................................... 362

2.125.4 Error Return Codes.. ............................................................................................. 364

2.126 query_dlus.........................................................................................................................365

2.126.1 Supplied Parameters.. ........................................................................................... 365

2.126.2 Returned Parameters............................................................................................ 366

2.126.3 Error Return Codes.. ............................................................................................. 368

2.127 query_domain_config_file................................................................................................. 369

2.127.1 Supplied Parameters.. ........................................................................................... 369

2.127.2 Returned Parameters............................................................................................ 369

2.127.3 Error Return Codes.. ............................................................................................. 369

2.128 query_downstream_lu.......................................................................................................370

2.128.1 Supplied Parameters.. ........................................................................................... 370

2.128.2 Returned Parameters: Summary Information.......................................................371

2.128.3 Returned Parameters: Detailed Information......................................................... 372

2.128.4 Error Return Codes.. ............................................................................................. 376

2.129 query_downstream_pu......................................................................................................377

2.129.1 Supplied Parameters.. ........................................................................................... 377

2.129.2 Returned Parameters............................................................................................ 378

2.129.3 Error Return Codes.. ............................................................................................. 380

2.130 query_dspu_template........................................................................................................381

2.130.1 Supplied Parameters.. ........................................................................................... 381

2.130.2 Returned Parameters............................................................................................ 381

2.130.3 Error Return Codes.. ............................................................................................. 383

2.131 query_emulator_user_def................................................................................................. 383

2.131.1 Supplied Parameters.. ........................................................................................... 383

2.131.2 Returned Parameters: Summary Information.......................................................384

2.131.3 Returned Parameters: Detailed Information......................................................... 384

2.131.4 Error Return Codes.. ............................................................................................. 387

2.132 query_focal_point..............................................................................................................387

2.132.1 Supplied Parameters.. ........................................................................................... 387

2.132.2 Returned Parameters............................................................................................ 388

xiv

2.132.3 Error Return Codes.. ............................................................................................. 390

2.133 query_global_log_type......................................................................................................390

2.133.1 Supplied Parameters.. ........................................................................................... 391

2.133.2 Returned Parameters............................................................................................ 391

2.133.3 Error Return Codes.. ............................................................................................. 392

2.134 query_isr_session............................................................................................................. 392

2.134.1 Supplied Parameters.. ........................................................................................... 392

2.134.2 Returned Parameters: Summary Information.......................................................393

2.134.3 Returned Parameters: Detailed Information......................................................... 394

2.134.4 Error Return Codes.. ............................................................................................. 396

2.135 query_kernel_memory_limit..............................................................................................397

2.135.1 Supplied Parameters.. ........................................................................................... 397

2.135.2 Returned Parameters............................................................................................ 397

2.135.3 Error Return Codes.. ............................................................................................. 398

2.136 query_local_lu...................................................................................................................398

2.136.1 Supplied Parameters.. ........................................................................................... 398

2.136.2 Returned Parameters: Summary Information.......................................................400

2.136.3 Returned Parameters: Detailed Information......................................................... 400

2.136.4 Error Return Codes.. ............................................................................................. 402

2.137 query_local_topology.........................................................................................................403

2.137.1 Supplied Parameters.. ........................................................................................... 403

2.137.2 Returned Parameters: Summary Information.......................................................404

2.137.3 Returned Parameters: Detailed Information......................................................... 405

2.137.4 Error Return Codes.. ............................................................................................. 407

2.138 query_log_file....................................................................................................................408

2.138.1 Supplied Parameters.. ........................................................................................... 408

2.138.2 Returned Parameters............................................................................................ 408

2.138.3 Error Return Codes.. ............................................................................................. 409

2.139 query_log_type..................................................................................................................409

2.139.1 Supplied Parameters.. ........................................................................................... 409

2.139.2 Returned Parameters............................................................................................ 409

2.139.3 Error Return Codes.. ............................................................................................. 410

2.140 query_ls.............................................................................................................................411

2.140.1 Supplied Parameters.. ........................................................................................... 411

2.140.2 Returned Parameters: Summary Information.......................................................412

2.140.3 Returned Parameters: Detailed Information......................................................... 414

2.140.4 Error Return Codes.. ............................................................................................. 429

2.141 query_ls_routing................................................................................................................430

2.141.1 Supplied Parameters.. ........................................................................................... 430

2.141.2 Returned Parameters............................................................................................ 431

2.141.3 Error Return Codes.. ............................................................................................. 431

2.142 query_lu_0_to_3.. ............................................................................................................. 432

2.142.1 Supplied Parameters.. ........................................................................................... 432

xv

2.142.2 Returned Parameters: Summary Information.......................................................434

2.142.3 Returned Parameters: Detailed Information......................................................... 435

2.142.4 Error Return Codes.. ............................................................................................. 443

2.143 query_lu_lu_password...................................................................................................... 443

2.143.1 Supplied Parameters.. ........................................................................................... 444

2.143.2 Returned Parameters ...........................................................................................445

2.143.3 Error Return Codes.. ............................................................................................. 445

2.144 query_lu_pool....................................................................................................................446

2.144.1 Supplied Parameters.. ........................................................................................... 446

2.144.2 Returned Parameters: Summary Information.......................................................447

2.144.3 Returned Parameters: Detailed Information......................................................... 447

2.144.4 Error Return Codes.. ............................................................................................. 448

2.145 query_lu62_timeout...........................................................................................................449

2.145.1 Supplied Parameters.. ........................................................................................... 449

2.145.2 Returned Parameters............................................................................................ 450

2.145.3 Error Return Codes.. ............................................................................................. 451

2.146 query_mds_application..................................................................................................... 452

2.146.1 Supplied Parameters.. ........................................................................................... 452

2.146.2 Returned Parameters............................................................................................ 452

2.146.3 Error Return Codes.. ............................................................................................. 453

2.147 query_mds_statistics.........................................................................................................453

2.147.1 Supplied Parameters.. ........................................................................................... 454

2.147.2 Returned Parameters............................................................................................ 454

2.147.3 Error Return Codes.. ............................................................................................. 455

2.148 query_mode...................................................................................................................... 455

2.148.1 Supplied Parameters.. ........................................................................................... 456

2.148.2 Returned Parameters: Summary Information.......................................................457

2.148.3 Returned Parameters: Detailed Information......................................................... 458

2.148.4 Error Return Codes.. ............................................................................................. 460

2.149 query_mode_definition......................................................................................................461

2.149.1 Supplied Parameters.. ........................................................................................... 461

2.149.2 Returned Parameters: Summary Information.......................................................462

2.149.3 Returned Parameters: Detailed Information......................................................... 462

2.149.4 Error Return Codes.. ............................................................................................. 462

2.150 query_mode_to_cos_mapping..........................................................................................463

2.150.1 Supplied Parameters.. ........................................................................................... 463

2.150.2 Returned Parameters............................................................................................ 464

2.150.3 Error Return Codes.. ............................................................................................. 464

2.151 query_nmvt_application.................................................................................................... 464

2.151.1 Supplied Parameters.. ........................................................................................... 465

2.151.2 Returned Parameters............................................................................................ 465

2.151.3 Error Return Codes.. ............................................................................................. 466

xvi

2.152 query_nn_topology_node..................................................................................................466

2.152.1 Supplied Parameters.. ........................................................................................... 466

2.152.2 Returned Parameters: Summary Information.......................................................468

2.152.3 Returned Parameters: Detailed Information......................................................... 468

2.152.4 Error Return Codes.. ............................................................................................. 470

2.153 query_nn_topology_stats..................................................................................................471

2.153.1 Supplied Parameters.. ........................................................................................... 471

2.153.2 Returned Parameters............................................................................................ 471

2.153.3 Error Return Codes.. ............................................................................................. 474

2.154 query_nn_topology_tg.......................................................................................................474

2.154.1 Supplied Parameters.. ........................................................................................... 474

2.154.2 Returned Parameters: Summary Information.......................................................476

2.154.3 Returned Parameters: Detailed Information......................................................... 477

2.154.4 Error Return Codes.. ............................................................................................. 480

2.155 query_node....................................................................................................................... 481

2.155.1 Supplied Parameters.. ........................................................................................... 481

2.155.2 Returned Parameters............................................................................................ 481

2.155.3 Error Return Codes.. ............................................................................................. 490

2.156 query_node_all..................................................................................................................490

2.156.1 Supplied Parameters.. ........................................................................................... 490

2.156.2 Returned Parameters............................................................................................ 491

2.156.3 Error Return Codes.. ............................................................................................. 491

2.157 query_node_limits.............................................................................................................492

2.157.1 Supplied Parameters.. ........................................................................................... 492

2.157.2 Returned Parameters............................................................................................ 492

2.157.3 Error Return Codes.. ............................................................................................. 495

2.158 query_partner_lu...............................................................................................................496

2.158.1 Supplied Parameters.. ........................................................................................... 496

2.158.2 Returned Parameters: Summary Information.......................................................497

2.158.3 Returned Parameters: Detailed Information......................................................... 498

2.158.4 Error Return Codes.. ............................................................................................. 500

2.159 query_partner_lu_definition...............................................................................................501

2.159.1 Supplied Parameters.. ........................................................................................... 501

2.159.2 Returned Parameters: Summary Information.......................................................502

2.159.3 Returned Parameters: Detailed Information......................................................... 503

2.159.4 Error Return Codes.. ............................................................................................. 503

2.160 query_port.........................................................................................................................504

2.160.1 Supplied Parameters.. ........................................................................................... 504

2.160.2 Returned Parameters: Summary Information.......................................................505

2.160.3 Returned Parameters: Detailed Information......................................................... 506

2.160.4 Error Return Codes.. ............................................................................................. 510

2.161 query_pu........................................................................................................................... 510

2.161.1 Supplied Parameters.. ........................................................................................... 510

2.161.2 Returned Parameters............................................................................................ 511

xvii

2.161.3 Error Return Codes.. ............................................................................................. 514

2.162 query_rcf_access..............................................................................................................515

2.162.1 Supplied Parameters.. ........................................................................................... 515

2.162.2 Returned Parameters............................................................................................ 515

2.162.3 Error Return Codes.. ............................................................................................. 516

2.163 query_rje_wkstn................................................................................................................516

2.163.1 Supplied Parameters.. ........................................................................................... 516

2.163.2 Returned Parameters: Summary Information.......................................................517

2.163.3 Returned Parameters: Detailed Information......................................................... 518

2.163.4 Error Return Codes.. ............................................................................................. 518

2.164 query_rje_wkstn_def.........................................................................................................519

2.164.1 Supplied Parameters.. ........................................................................................... 519

2.164.2 Returned Parameters: Summary Information.......................................................520

2.164.3 Returned Parameters: Detailed Information......................................................... 520

2.164.4 Error Return Codes.. ............................................................................................. 520

2.165 query_rtp_connection........................................................................................................521

2.165.1 Supplied Parameters.. ........................................................................................... 521

2.165.2 Returned Parameters: Summary Information.......................................................522

2.165.3 Returned Parameters: Detailed Information......................................................... 523

2.165.4 Error Return Codes.. ............................................................................................. 527

2.166 query_rtp_tuning............................................................................................................... 527

2.166.1 Supplied Parameters.. ........................................................................................... 527

2.166.2 Returned Parameters............................................................................................ 527

2.166.3 Error Return Codes.. ............................................................................................. 528

2.167 query_security_access_list.. ............................................................................................. 528

2.167.1 Supplied Parameters.. ........................................................................................... 529

2.167.2 Returned Parameters............................................................................................ 529

2.167.3 Error Return Codes.. ............................................................................................. 530

2.168 query_session...................................................................................................................530

2.168.1 Supplied Parameters.. ........................................................................................... 530

2.168.2 Returned Parameters: Summary Information.......................................................532

2.168.3 Returned Parameters: Detailed Information......................................................... 532

2.168.4 Error Return Codes.. ............................................................................................. 536

2.169 query_sna_net.. ................................................................................................................537

2.169.1 Supplied Parameters.. ........................................................................................... 537

2.169.2 Returned Parameters............................................................................................ 538

2.169.3 Error Return Codes.. ............................................................................................. 538

2.170 query_statistics..................................................................................................................538

2.170.1 Supplied Parameters.. ........................................................................................... 539

2.170.2 Returned Parameters: SDLC LS Statistics...........................................................540

2.170.3 Returned Parameters: SDLC LS Operational Information....................................543

2.170.4 Returned Parameters: SDLC Port Statistics.........................................................545

2.170.5 Returned Parameters: SDLC Port Operational Information................................. 546

xviii

2.170.6 Returned Parameters: Token Ring / Ethernet / FDDI LS Statistics......................548

2.170.7 Returned Parameters: Token Ring, Ethernet, or FDDI Port Statistics................. 548

2.170.8 Returned Parameters: Enterprise Extender..........................................................550

2.170.9 Error Return Codes.. ............................................................................................. 550

2.171 query_tn3270_access_def................................................................................................551

2.171.1 Supplied Parameters.. ........................................................................................... 551

2.171.2 Returned Parameters: Summary Information.......................................................552

2.171.3 Returned Parameters: Detailed Information......................................................... 553

2.171.4 Error Return Codes.. ............................................................................................. 555

2.172 query_tn3270_association................................................................................................ 555

2.172.1 Supplied Parameters.. ........................................................................................... 555

2.172.2 Returned Parameters............................................................................................ 556

2.172.3 Error Return Codes.. ............................................................................................. 556

2.173 query_tn3270_defaults......................................................................................................557

2.173.1 Supplied Parameters.. ........................................................................................... 557

2.173.2 Returned Parameters............................................................................................ 557

2.173.3 Error Return Codes.. ............................................................................................. 558

2.174 query_tn_server_trace...................................................................................................... 558

2.174.1 Supplied Parameters.. ........................................................................................... 558

2.174.2 Returned Parameters............................................................................................ 558

2.174.3 Error Return Codes.. ............................................................................................. 559

2.175 query_tp............................................................................................................................ 559

2.175.1 Supplied Parameters.. ........................................................................................... 559

2.175.2 Returned Parameters............................................................................................ 560

2.175.3 Error Return Codes.. ............................................................................................. 561

2.176 query_tp_definition............................................................................................................561

2.176.1 Supplied Parameters.. ........................................................................................... 562

2.176.2 Returned Parameters: Summary Information.......................................................562

2.176.3 Returned Parameters: Detailed Information......................................................... 563

2.176.4 Error Return Codes.. ............................................................................................. 563

2.177 query_tp_load_info............................................................................................................564

2.177.1 Supplied Parameters.. ........................................................................................... 564

2.177.2 Returned Parameters............................................................................................ 564

2.177.3 Error Return Codes.. ............................................................................................. 566

2.178 query_trace_file.................................................................................................................566

2.178.1 Supplied Parameters.. ........................................................................................... 566

2.178.2 Returned Parameters............................................................................................ 567

2.178.3 Error Return Codes.. ............................................................................................. 568

2.179 query_trace_type...............................................................................................................568

2.179.1 Supplied Parameters.. ........................................................................................... 568

2.179.2 Returned Parameters............................................................................................ 568

2.179.3 Error Return Codes.. ............................................................................................. 569

2.180 query_userid_password....................................................................................................570

xix

2.180.1 Supplied Parameters.. ........................................................................................... 570

2.180.2 Returned Parameters............................................................................................ 571

2.180.3 Error Return Codes.. ............................................................................................. 571

2.181 remove_dlc_trace.. ............................................................................................................571

2.181.1 Supplied Parameters.. ........................................................................................... 572

2.181.2 Returned Parameters............................................................................................ 573

2.181.3 Error Return Codes.. ............................................................................................. 573

2.182 reset_session_limit............................................................................................................574

2.182.1 Supplied Parameters.. ........................................................................................... 575

2.182.2 Returned Parameters............................................................................................ 576

2.182.3 Error Return Codes.. ............................................................................................. 577

2.183 set_bck_cs_trace...............................................................................................................579

2.183.1 Supplied Parameters.. ........................................................................................... 579

2.183.2 Returned Parameters............................................................................................ 580

2.183.3 Error Return Codes.. ............................................................................................. 580

2.184 set_buffer_availability.. ...................................................................................................... 581

2.184.1 Supplied Parameters.. ........................................................................................... 581

2.184.2 Returned Parameters............................................................................................ 581

2.184.3 Error Return Codes.. ............................................................................................. 581

2.185 set_central_logging...........................................................................................................581

2.185.1 Supplied Parameters.. ........................................................................................... 581

2.185.2 Returned Parameters............................................................................................ 582

2.185.3 Error Return Codes.. ............................................................................................. 582

2.186 set_cs_trace...................................................................................................................... 582

2.186.1 Supplied Parameters.. ........................................................................................... 583

2.186.2 Returned Parameters............................................................................................ 584

2.186.3 Error Return Codes.. ............................................................................................. 584

2.187 set_global_log_type.......................................................................................................... 585

2.187.1 Supplied Parameters.. ........................................................................................... 585

2.187.2 Returned Parameters............................................................................................ 586

2.187.3 Error Return Codes.. ............................................................................................. 586

2.188 set_kernel_memory_limit.................................................................................................. 587

2.188.1 Supplied Parameters.. ........................................................................................... 587

2.188.2 Returned Parameters............................................................................................ 587

2.188.3 Error Return Codes.. ............................................................................................. 587

2.189 set_log_file........................................................................................................................588

2.189.1 Supplied Parameters.. ........................................................................................... 588

2.189.2 Returned Parameters............................................................................................ 590

2.189.3 Error Return Codes.. ............................................................................................. 590

2.190 set_log_type......................................................................................................................590

2.190.1 Supplied Parameters.. ........................................................................................... 590

2.190.2 Returned Parameters............................................................................................ 592

2.190.3 Error Return Codes.. ............................................................................................. 592

xx

2.191 set_tn_server_trace...........................................................................................................593

2.191.1 Supplied Parameters.. ........................................................................................... 593

2.191.2 Returned Parameters............................................................................................ 593

2.191.3 Error Return Codes.. ............................................................................................. 593

2.192 set_trace_file..................................................................................................................... 594

2.192.1 Supplied Parameters.. ........................................................................................... 594

2.192.2 Returned Parameters............................................................................................ 595

2.192.3 Error Return Codes.. ............................................................................................. 596

2.193 set_trace_type...................................................................................................................596

2.193.1 Supplied Parameters.. ........................................................................................... 596

2.193.2 Returned Parameters............................................................................................ 598

2.193.3 Error Return Codes.. ............................................................................................. 598

2.194 start_dlc.............................................................................................................................599

2.194.1 Supplied Parameters.. ........................................................................................... 599

2.194.2 Returned Parameters............................................................................................ 599

2.194.3 Error Return Codes.. ............................................................................................. 599

2.195 start_internal_pu...............................................................................................................600

2.195.1 Supplied Parameters.. ........................................................................................... 600

2.195.2 Returned Parameters............................................................................................ 600

2.195.3 Error Return Codes.. ............................................................................................. 601

2.196 start_ls...............................................................................................................................602

2.196.1 Supplied Parameters.. ........................................................................................... 602

2.196.2 Returned Parameters............................................................................................ 603

2.196.3 Error Return Codes.. ............................................................................................. 603

2.197 start_port...........................................................................................................................604

2.197.1 Supplied Parameters.. ........................................................................................... 604

2.197.2 Returned Parameters............................................................................................ 605

2.197.3 Error Return Codes.. ............................................................................................. 605

2.198 status_all...........................................................................................................................606

2.198.1 Supplied Parameters.. ........................................................................................... 606

2.198.2 Returned Information.............................................................................................606

2.198.3 Error Return Codes.. ............................................................................................. 608

2.199 status_connectivity.. .......................................................................................................... 608

2.199.1 Supplied Parameters.. ........................................................................................... 608

2.199.2 Returned Information.............................................................................................608

2.199.3 Error Return Codes.. ............................................................................................. 609

2.200 status_dependent_lu.........................................................................................................609

2.200.1 Supplied Parameters.. ........................................................................................... 609

2.200.2 Returned Information.............................................................................................610

2.200.3 Error Return Codes.. ............................................................................................. 612

2.201 status_dlur.........................................................................................................................613

2.201.1 Supplied Parameters.. ........................................................................................... 613

2.201.2 Returned Information.............................................................................................613

xxi

2.201.3 Error Return Codes.. ............................................................................................. 613

2.202 status_lu62........................................................................................................................614

2.202.1 Supplied Parameters.. ........................................................................................... 614

2.202.2 Returned Information.............................................................................................614

2.202.3 Error Return Codes.. ............................................................................................. 614

2.203 status_node.......................................................................................................................615

2.203.1 Supplied Parameters.. ........................................................................................... 615

2.203.2 Returned Information.............................................................................................615

2.203.3 Error Return Codes.. ............................................................................................. 615

2.204 status_remote_node..........................................................................................................616

2.204.1 Parameters.. .......................................................................................................... 616

2.204.2 Returned Information.............................................................................................616

2.204.3 Error Return Codes.. ............................................................................................. 617

2.205 stop_dlc.............................................................................................................................617

2.205.1 Supplied Parameters.. ........................................................................................... 617

2.205.2 Returned Parameters............................................................................................ 618

2.205.3 Error Return Codes.. ............................................................................................. 618

2.206 stop_internal_pu................................................................................................................618

2.206.1 Supplied Parameters.. ........................................................................................... 619

2.206.2 Error Return Codes.. ............................................................................................. 619

2.207 stop_ls...............................................................................................................................620

2.207.1 Supplied Parameters.. ........................................................................................... 620

2.207.2 Returned Parameters............................................................................................ 621

2.207.3 Error Return Codes.. ............................................................................................. 621

2.208 stop_port.. ......................................................................................................................... 622

2.208.1 Supplied Parameters.. ........................................................................................... 622

2.208.2 Returned Parameters............................................................................................ 622

2.208.3 Error Return Codes.. ............................................................................................. 622

2.209 term_node.........................................................................................................................623

2.209.1 Supplied Parameters.. ........................................................................................... 623

2.209.2 Returned Parameters............................................................................................ 624

2.209.3 Error Return Codes.. ............................................................................................. 624

Appendix A Common Return Codes from snapadmin Commands...............................................625

A.1 Communications Subsystem Not Active...............................................................................625

A.2 Function Not Supported....................................................................................................... 625

A.3 Parameter Check.................................................................................................................. 626

A.4 State Check.. ........................................................................................................................ 626

A.5 System Error.........................................................................................................................626

Appendix B Configuration Files.. .......................................................................................................628

B.1 Initial Configuration Files...................................................................................................... 628

xxii

B.2 Configuration File Format.....................................................................................................628

B.2.1 Record Ordering in a Configuration File.. ......................................................................... 629

B.2.2 Record Format...................................................................................................................629

B.2.3 Subrecord Format..............................................................................................................630

B.3 Changes Made to the Configuration Files by the Motif Administration Program.................630

B.4 File Input to the snapadmin Program...................................................................................631

B.4.1 Sample snapadmin Input Files.......................................................................................... 631

B.4.2 Sample Files Delivered with SNAplus2............................................................................. 632

Appendix C Environment Variables................................................................................................... 633

C.1 Environment Variables That Affect All Functions.. ............................................................... 633

C.1.1 LANG.................................................................................................................................633

C.1.2 PATH..................................................................................................................................633

C.2 Environment Variables That Affect 3270 Emulation.............................................................633

C.2.1 CONVERTTRANS............................................................................................................. 633

C.2.2 IND_FILE...........................................................................................................................633

C.2.3 LANG.................................................................................................................................634

C.2.4 SNAP3270_LOWER_RIGHT.............................................................................................634

C.2.5 SNAP3270_SI and SNAP3270_SO.................................................................................. 634

C.2.6 SNAP3270_SPLIT_CHAR.................................................................................................634

C.2.7 SNABLANKSCREEN.........................................................................................................634

C.2.8 SNALU1MPP......................................................................................................................635

C.2.9 SNAMSG...........................................................................................................................635

C.2.10 SNAP3270_COLOR........................................................................................................635

C.2.11 SNAPRMPL.....................................................................................................................635

C.3 Environment Variables That Affect RJE Workstations......................................................... 635

C.3.1 SNABLANKSCREEN.........................................................................................................635

C.3.2 SNAMSG...........................................................................................................................635

C.4 Environment Variables That Affect APPC and CPI-C Communications..............................636

C.4.1 APPCLLU...........................................................................................................................636

C.4.2 APPCTPN..........................................................................................................................636

C.4.3 SHLIB_PATH......................................................................................................................636

C.4.4 CLASSPATH...................................................................................................................... 636

C.5 Environment Variables That Affect the CSV API.. ............................................................... 636

C.5.1 SNATBLG.. ........................................................................................................................ 636

C.6 Environment Variables That Affect the Command-Line Administration Program................637

C.6.1 COLUMNS.........................................................................................................................637

C.7 Environment Variables That Affect Tracing.. ........................................................................ 637

C.7.1 SNATRC.............................................................................................................................637

C.7.2 SNACTL.............................................................................................................................637

C.7.3 SNATRACESIZE................................................................................................................637

C.7.4 SNATRCRESET.................................................................................................................637

C.7.5 SNATRUNC.......................................................................................................................638

xxiii

Legal Notices

Trademark Notices

Legal Notices

The information in this document is subject to change without notice.

Hewlett-Packard makes no warranty of any kind with regard to this manual, including, but not limited to, the implied
warranties of merchantability and fitness for a particular purpose. Hewlett-Packard shall not be held liable for errors

contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing,
performance, or use of this material.

Warranty

A copy of the specific warranty terms applicable to your Hewlett-Packard product and replacement parts can be
obtained from your local Sales and Service Office.

U.S. Government License

Proprietary computer software. Valid license from HP required for possession, use or copying. Consistent with
FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data
for Commercial Items are licensed to the U.S. Government under vendor’s standard commercial license.

Copyright Notices

Reproduction, adaptation, or translation of this document without prior written permission is prohibited, except as
allowed under the copyright laws.

©copyright 1989-2005 Hewlett-Packard Development Company, L.P.

Trademark Notices

UNIX is a registered trademark in the United States and other countries, licensed exclusively through The Open
Group.

24

Publishing History

New and Changed Information in This Edition

Publishing History

The manual publishing date and part number indicate its current edition. The publishing date will change when a
new edition is printed. Minor changes may be made without changing the publishing date. The manual part number
will change when extensive changes are made.

Manual updates may be issued between editions to correct errors or document product changes. To ensure that you
receive the updated or new editions, you should subscribe to the appropriate product support service. See your HP
sales representative for details.

Edition 1: March 1998

Edition 2: October 1998

Edition 3: June 2001

Edition 4: April 2005

New and Changed Information in This Edition

SNAplus2 can now operate as an APPN Network Node, which resides in the backbone of an APPN network and
provides resource location and session routing facilities. Alternatively, it can still operate as an End Node or LEN
Node (as in earlier versions).

SNAplus2 can also operate as a Branch Network Node, allowing the APPN network to be separated into branches
to simplify its topology and reduce network management overheads. A Branch Network Node provides network
node functions to end nodes in a branch separated from the main APPN network, while acting as an end node in
the main network itself.

The High-Performance Routing (HPR) feature of APPN is now included. This provides Rapid Transport Protocol
(RTP), minimizing cycles and storage requirements for routing network layer packets through intermediate nodes on
a session route, and Automatic Network Routing (ANR), enabling APPN networks to automatically reroute sessions
if a portion of the originally computed route fails.

Enterprise Extender (HPR/IP) connectivity is now included. This provides HPR functionality over IP connections,
to support SNA applications connected over an IP network.

25

Before You Begin

About This Book

Before You Begin

HP-UX SNAplus2 Administration Command Reference contains information about starting and managing the
SNAplus2 software. SNAplus2 is a software product that enables a server running HP-UX to exchange information
with other nodes on an SNA network.

This book applies to Release 7 of SNAplus2. Token Ring and FDDI adapters are not supported on HP-UX 11i v3.

Prerequisite Knowledge

Before reading this manual, you should have a knowledge of SNA and APPN concepts. See the Related publications
section for details of manuals that provide this information.

About This Book

This section explains how information is organized and presented in this book.

Organization of This Book

This book is organized as follows:

• Chapter 1, Introduction to SNAplus2 Administration Commands, provides an overview of the tasks involved
in administering SNAplus2, provides an overview of how to use the
describes characteristics (such as parameter type) that are common to parameters used by all commands.

• Chapter 2, Administration Commands, provides detailed information about the parameters required for specific
administration operations such as defining, starting, or querying a particular resource.

• Appendix A, Common Return Codes from snapadmin Commands, lists error return codes that are common to
all commands.

• Appendix B, Configuration Files, describes the contents of the data files that control how SNAplus2 operates
and explains how to modify these files if required.

• Appendix C, Environment Variables, provides a brief summary of all the environment variables that are used by
SNAplus2 programs.

snapadmin administration program, and

Typographic Conventions

Table 1, Typographic Conventions shows the typographic styles used in this document.

Table 1 Typographic Conventions

Special Element Sample of Typography

Document title

File or path name

Directory name

26

HP-UX SNAplus2 Administration Command Reference

sna.err

/var/opt/sna

Special Element Sample of Typography

Before You Begin

SNAplus2 Publications

Program or application

Command or utility

snapadmin

define_node; snaphelp

General reference to all commands of a particular type For example, query_* indicates all the administration

records that query details of a SNAplus2 resource

query_cn, query_cos, query_dlc, and so on).

(

Option or flag

Parameter

Literal value or selection that the user can enter

-d

lu_name

255

(including default values)

Constant (one of several possible parameter values)

Return value

FIRST_IN_LIST

INVALID_LU_ALIAS

Variable representing a supplied value infile

Environment variable

User input

LD_RUN_PATH

snapadmin

status_dependent_lu,pu_name=ETH0

Function, call, or entry point

Data structure

Field name (in a data structure)

ctime()

alert_3270_data

c_cflag

Keyboard keys

Hexadecimal value

[ENTER]

0x20

SNAplus2 Publications

SNAplus2 publications include user guides, administrator guides, and programmer guides. The following sections
describe the contents of each book.

Publications for Users

SNAplus2 provides the following user guides:

HP-UX SNAplus2 General Information

Provides a general overview of the SNAplus2 product.

HP-UX SNAplus2 3270 User’s Guide

Explains how to perform the following functions when you use 3270 emulation:

• Starting and stopping 3270 emulation

• Transferring files

• Using customization features such as remapping your keyboard and displaying colors

• Interpreting status-line information

27

Before You Begin

SNAplus2 Publications

• Sending NetView user alerts

• Viewing response times

HP-UX SNAplus2 RJE User’s Guide

Explains how to start and stop the RJE workstation, queue a job for submission to the host, list the queued
jobs, cancel a queued job, and send commands to the host’s job entry subsystem (JES).

HP-UX SNAplus2 APPC Application Suite User’s Guide

Explains how to use the set of six utility applications supplied with SNAplus2 that can be run over an SNA
network using SNAplus2. These applications use independent LU 6.2 protocols to communicate with similar
applications running on other nodes in an SNA network.

SNAplus2 Glossary

Provides a comprehensive list of terms and their definitions used in the SNAplus2 library.

Publications for Administrators

SNAplus2 provides the following administrator guides:

HP-UX SNAplus2 Installation

Explains how to install the SNAplus2 software and set up system files.

HP-UX SNAplus2 Migration Guide

Provides information about upgrading to the current version of SNAplus2 from previous versions. It includes
information about converting configuration files, rebuilding applications that use the SNAplus2 application
program interfaces (APIs), and changes in other SNAplus2 functions.

HP-UX SNAplus2 Administration Guide

Explains how to enable, configure, and manage SNAplus2. This guide provides information about SNA
concepts, and an overview of the features provided by SNAplus2. It describes how to configure and manage
SNAplus2 using the Motif administration program, and provides guidance for users of the command-line
administration program.

HP-UX SNAplus2 Administration Command Reference

Explains how to use the SNAplus2 command-line administration program and shows the syntax of all
SNAplus2 administration commands.

HP-UX SNAplus2 Diagnostics Guide

Explains how to investigate and resolve common problems and provides an overview of diagnostic tools,
including logging and tracing.

Publications for Programmers

SNAplus2 provides the following programmer guides. Each guide includes conceptual and detailed reference
information.

HP-UX SNAplus2 APPC Programmer’s Guide

Contains the information you need to write application programs using Advanced Program-to-Program
Communication (APPC).

HP-UX SNAplus2 CPI-C Programmer’s Guide

Contains the information you need to write application programs using Common Programming Interface for
Communications (CPI-C).

HP-UX SNAplus2/TN3270 HLLAPI Programmer’s Guide

28

Before You Begin

Related Publications

Contains the information you need to write application programs using High-Level Language Application
Program Interface (HLLAPI).

HP-UX SNAplus2 LUA Programmer’s Guide

Contains the information you need to write applications using the Conventional LU Application Programming
Interface (LUA).

HP-UX SNAplus2 CSV Programmer’s Guide

Contains the information you need to write application programs using the Common Service Verbs (CSV)
API.

HP-UX SNAplus2 MS Programmer’s Guide

Contains the information you need to write applications using the Management Services (MS) API.

HP-UX SNAplus2 NOF Programmer’s Guide

Contains the information you need to write applications using the Node Operator Facility (NOF) API.

Related Publications

For information about SNA, APPN or LU 6.2 architecture, refer to the following IBM documents:

• IBM Systems Network Architecture: LU6.2 Reference: Peer Protocols SC31-6808

• IBM Systems Network Architecture: APPN Architecture Reference SC30-3422.

• IBM Systems Network Architecture: Management Services SC30-3346

• IBM Systems Network Architecture: Formats GA27-3136

• IBM APPN Architecture and Product Implementations Tutorial GG24-3669

• IBM AS/400 Advanced Peer-to-Peer Networking GG24-3287

• IBM Communications Manager/2 System Management Programming Reference SC31-6173

• IBM Communications Manager/2 APPC Programming Guide and Reference SC31-6160

• IBM System/370 Principles of Operation GA22-7000

• IBM Systems Network Architecture: Technical Overview GC30-3073

29

Introduction to SNAplus2 Administration Commands

1 Introduction to SNAplus2 Administration
Commands

SNAplus2 administration commands are accessible through the snapadmin
command-line administration program that can be used to configure and manage the SNAplus2 node. The HP-
UX SNAplus2 Administration Guide describes how to configure and manage the SNAplus2 node using specific
administration commands.

This book describes how to use the
Administration commands are used for configuring, checking status of, and managing resources. Most administration
commands belong to one of these categories as follows:

Configuring

The following types of commands are used to configure resources:

define_*

Creates a new define_* record in the configuration file, or replaces a record for the same resource
with the new definition.

delete_*

Removes the corresponding define_* record from the file.

Checking status

The following types of commands are used to check the configuration and status of resources:

query_*

Returns information from the configuration file on the appropriate resource, but does not modify the
file.

status_*

snapadmin

program and the commands that you can issue through

program. The

snapadmin program is a

snapadmin.

Provides summary information about the state of resources.

Managing

The following types of commands are used to manage resources:

start_*, init_*,oractivate_*

Explicitly starts a configured resource. Some resources can be activated implicitly as a result of
activating other resources.

stop_*, term_*,ordeactivate_*

Explicitly stops a resource. Some resources can be stopped implicitly (for example, as a result of a
period of inactivity).

set_*

Sets tracing and logging parameters.

Administrative commands are listed alphabetically in Chapter 2, Administration Commands.

30

Introduction to SNAplus2 Administration Commands

Using snapadmin

1.1 Using snapadmin

Before you can use the snapadmin program, SNAplus2 must be started. If SNAplus2 has not been started, enter
the following command on the HP-UX command line:

sna start

You can use

snapadmin

to configure and manage SNAplus2. Use

snapadmin

as an alternative to the Motif

administration program when any of the following is true:

• You want to configure resource parameters that are not frequently used.

• You do not have X display capabilities.

When you issue a command or use the Motif administration program, SNAplus2 changes the configuration file. For
more information about configuration files, see Appendix B,

Configuration Files.

For more information about using the Motif administration program, refer to HP-UX SNAplus2 Administration
Guide.

Use the following syntax for

snapadmin [-n node][-d][-a][-h]
<-i infile>|
<command, parameter1=value1, parameter2=value2, …>

snapadmin:

For information about the options you can use on the command line, see Section 1.1.1, Command Line Options.
For information about parameter syntax, see Section 1.1.2, Parameter Syntax Used for Administration Commands.

Administrative commands are listed alphabetically in Chapter 2, Administration Commands, and include descriptions
containing the following:

• Purpose of the command

• Whether the command can be issued to an active node or an inactive node or to the domain configuration file

• Other commands that must precede it

• Details about the parameters for the command, including parameter types and default values

• Returned information

1.1.1 Command Line Options

You can use one or more of the following options when you use the

-n node

Sends the command to the named node. By default, node commands are sent to the local node.

Some administration commands defined in Chapter 2, Administration Commands, which are used to control
Client-Server tracing, explicitly say that they can be issued on a HP-UX client. For all other commands, you
can only issue command-line administration commands from a client if you specify -n with a server name.

The node name is a string of 1–128 characters. If it includes a . (period) character, SNAplus2 assumes that
it is a fully-qualified name; otherwise it performs a DNS lookup to determine the node name.

-d

List detailed information.

-a

List all items (query_* commands only).

snapadmin program:

31

Introduction to SNAplus2 Administration Commands

Using snapadmin

You do not need to specify -a to list all resources of a particular type. The -a option is implied by default
if no particular resource is named.

-h

Display help. For more information, see Section 1.1.1, Command Line Options.

-c

Change a particular parameter (available on a select number of define_ commands only). For more
information, see Section 1.1.1, Command Line Options.

-i infile

Use commands from the named file.

Changing Specific Parameters

The command line option -c enables the user to change a specific parameter on an existing command without
reentering the entire command. Specify the command name and parameter to be changed on the command line.
This option is supported only for the following commands (an error message is returned for all other commands):

• define_cpic_side_info

• define_downstream_lu

• define_ethernet_dlc

• define_ethernet_ls

• define_ethernet_port

• define_ip_dlc

• define_ip_ls

• define_ip_port

• define_local_lu

• define_lu_0_to_3

• define_mode

• define_node

• define_partner_lu

• define_qllc_dlc

• define_qllc_ls

• define_qllc_port

• define_rje_wkstn

• define_sdlc_dlc

• define_sdlc_ls

• define_sdlc_port

• define_tp

• define_tr_dlc

32

• define_tr_ls

• define_tr_port

• define_userid_password

Using Command Line Help

Introduction to SNAplus2 Administration Commands

Using snapadmin

Help is available using the -h and -d options on

snapadmin

-h

snapadmin

as follows:

Displays general information about administration
commands and instructions for specifying commands
and parameters on the command line.

snapadmin

snapadmin

snapadmin

-h -d

-h command

-h -d command

Lists all administration commands.

Displays a description of the specified command.

Displays a description of the specified command and
lists the parameters for this command.

1.1.2 Parameter Syntax Used for Administration Commands

Use the syntax described in the following sections to specify parameters in administration commands. The
information included in these sections applies to both configuration files and
indicated.

The parameters in a command can be specified in any order, except as noted in Section 1.1.2, Parameter Syntax
Used for Administration Commands.

Parameter Types

Each parameter in an administration command is one of the following types:

Character

snapadmin commands, except where

A character string entered using locally displayable characters (for example the lu_name parameter value).
The individual parameter descriptions give details of the maximum and minimum length of each string. The
parameter descriptions also indicate when the string must consist of characters from a particular character set
(such as alphanumeric, type-A, or HP-UX file name characters). Otherwise, you can use any character that
is displayable in your computer’s local character set. Character strings are case-sensitive.

If you enter a character string as command-line input to the

snapadmin program and the string contains one

or more commas, you must precede each comma with % so that the program does not interpret the comma as
a separator between parameters. To enter a % character by itself, use two % characters—%%. (This appears
as %% in configuration files and in text output from administration commands, but is interpreted as a single
character.)

A name parameter entered as a character string that starts with the @ character is reserved and should not be
used. An exception is the resource_name parameter on the add_dlc_trace and remove_dlc_trace
commands. Also, avoid using names that start with the $ character because you may overwrite a name
reserved for the system. Currently, all names starting with $G are used by the system.

Do not enclose character strings in quotation marks (""). If you need to include quotation marks within a
character string, the following restrictions apply:

• The " character must be a valid character for the parameter you are defining.

• The string must contain an even number of quotation marks.

• Each quotation mark must be preceded by a backslash character, \", to avoid interpretation by the HP-UX

shell.

33

Introduction to SNAplus2 Administration Commands

Using snapadmin

Decimal

A numeric value (for example 128). The individual parameter descriptions give details of the maximum and
minimum values. Specify numeric values in decimal, not in hexadecimal, unless the values are explicitly
defined as hex numbers.

Hex number

A numeric value given in hexadecimal, specified as an even number of hexadecimal digits preceded by 0x
(for example 0xF0). A hex number is normally one byte, specified as two hexadecimal digits, unless a length
is explicitly specified; for example,
(a four-byte value specified as eight hexadecimal digits).

The individual parameter descriptions give details of the maximum and minimum values or any other
restrictions on the valid values if applicable. If no restrictions are noted, you can use any value. The
characters A–F are not case-sensitive; you can use either uppercase or lowercase.

Hex array

An array of hexadecimal digits, which can be represented either by enclosing the digits in angle brackets
(for example <010A0B0C>) or by preceding the digits with 0x. The individual parameter descriptions give
details of the maximum and minimum length of the array, and any restrictions on its value. The characters
A–F are not case-sensitive; you can use either uppercase or lowercase.

sense_data on deactivate_session is defined to have a length of 4

If you are entering a hex array as command-line input to the
bracket by a backslash character (

Constant

One of two or more defined values, specified as an ASCII character string without quotation marks (for
example PRIMARY). Defined constants are used for parameters that have a fixed set of valid values, such as
PRIMARY / SECONDARY / NEGOTIABLE; the individual parameter descriptions list the defined values for
each parameter. Defined constants are not case-sensitive; you can use either uppercase or lowercase.

The command descriptions list the type for each parameter.

\< or \>), to avoid interpretation by the HP-UX shell.

snapadmin program, you must precede each angle

Default Parameter Values

Some administration command parameters, such as the name of the resource you are defining or starting, must always
be explicitly specified. For other parameters, SNAplus2 provides default values. For a standard configuration, you
do not need to specify every parameter in a command. The individual parameter descriptions include information
about default values where applicable. If no default value is shown for a parameter, you must specify it explicitly.

The default parameter values used for administration command parameters can be different from the default values
used for the Motif administration program.

Blank Space

Embedded space characters are valid within character strings only when the string’s character set allows them, and
are not valid within any other type of parameter value. For example:

• The character string LU001 is valid for the lu_name parameter.

• The character string LU 001 is valid for the description parameter which allows any characters (including

spaces), but not for the lu_name parameter which does not allow space characters.

• The hex array <01020304> is valid.

• The hex array <01 02 03 04> is not valid.

All blank space before or after descriptors, parameter names, or parameter values (that is, any combination of spaces
and tabs) is ignored.

There is no need to use quotation marks ("") around parameter values containing spaces.

34

Introduction to SNAplus2 Administration Commands

Using snapadmin

Subrecords in Administration Commands

Some administration commands include data whose format can vary between instances of the command. For
example, define_emulator_user, which defines a 3270 or 5250 emulation program user, includes a variable
number of sessions for the user. To allow for this, the variable data is specified in optional subrecords. This means
that a command consists of a series of parameters common to all instances of that command type, followed by
subrecords containing the variable data.

All commands have the following order:

1. The

2. Common parameters

All commands that have one or more subrecords have the following order:

1. The command_name

2. Common parameters

3. A

4. Parameters associated with that

command_name

subrecord_name, in braces { }

subrecord_name

5. Further instances of the

In a configuration file, each of these names and parameters is on a separate line; in a command issued to

subrecord_name, each followed by the parameters associated with it

snapadmin,

they are separated by commas.

All the parameters associated with the command_name (and not with a subrecord) must be listed after the
command_name and before the first
must be listed after that

subrecord_name and before the next

subrecord_name; all the parameters associated with a particular

subrecord_name, if any, or the next command_name.

subrecord_name

However, the order of individual parameters within a subrecord (or within the common parameters) is not important.

List Options on query_* Commands

You can obtain information about SNAplus2 resources by issuing a query_* command for the appropriate resource
type. For example, you can obtain information about the configuration and status of an LS by issuing query_ls.A
query_* command can return information about a specific resource (for example, the configuration of a particular
LS) or about multiple resources of the same type (for example, information about all configured link stations),
depending on the options used. In addition, some query_* commands have the option of returning either summary
or detailed information about the specified resources.

Note

Most users will not need to use the num_entries and list_options parameters described in
this section. Instead, you can use the command-line options -a and -d with the
command to specify which entry or entries you want and the level of detail you need:

• To return a single named entry, specify the resource name of the entry you want, and

do not specify the -a option.

• To return all entries, specify the -a option and do not specify a resource name.

• To return detailed information (either for a single named entry or for multiple entries),

add the -d option to the command.

snapadmin

For more information about these options, see Section 1.1.1, Command Line Options.

Obtaining Information About a Single Resource or Multiple Resources

You can think of the information returned by query_* commands as being stored in the form of a list, ordered
according to the name of the resource. For example, the information returned by query_ls is in order of LS
name. The normal order of the list is as follows:

35

Introduction to SNAplus2 Administration Commands

Using snapadmin

• By name length (shortest name first)

• By ASCII lexicographical ordering for names of the same length

Individual command descriptions note when the list ordering differs from the preceding order (for example, when
the list is ordered by a numeric value).

You can obtain information about multiple resources by requesting the complete list or a specified part of it. The
following parameters on the

query_* command determine which entries from the list are returned:

num_entries

Maximum number of resources for which information should be returned. You can specify 1 to return a
specific entry, a number greater than 1 to return multiple entries, or 0 (zero) to return all entries. The default
is to return all entries if you specify only the name of the query command and do not specify

num_entries or

the resource name, or to return one entry if you do not specify num_entries but do specify the resource name.

list_options

The position in the list of the first entry required, specified by one of the following options:

FIRST_IN_LIST

First entry in the list

LIST_INCLUSIVE

Entries starting from a specific named entry

LIST_FROM_NEXT

Entries starting from the next entry after a specific named entry. The name specified gives the starting
position according to the list ordering; the name need not exist in the list. For example, if the list
contains entries NODEA, NODEB, NODED, NODEF, and the application requests entries starting
from the first entry after NODEC, the first entry returned is NODED.

If the list_options parameter is set to LIST_INCLUSIVE or LIST_FROM_NEXT, another parameter on the com­mand specifies the name of an entry in the list that gives the starting position for the required entries. The description
of list_options in each command description explains which parameter is used to identify the starting position. If
you specify one of these options but do not specify the parameter giving the starting position, the list_options pa­rameter is ignored and the returned information starts from the first entry in the list.

To request all entries in the list when using the

snapadmin

program, you can use the command-line option -a instead

of specifying num_entries as 0 and list_options as FIRST_IN_LIST (also, the default is to return all entries when

num_entries and the resource name are not specified). This option returns all entries unless you explicitly set
num_entries or list_options to return specific entries.

The number of entries returned is the smaller of the following values:

• The num_entries parameter, if this is nonzero

• The number of entries between the specified starting position and the end of the list

Obtaining Summary or Detailed Information

Some query_* commands provide the option of returning summary or detailed information about the specified
resources. For example, query_local_lu can return only the LU name, LU alias and description (summary
information), or it can also return additional information such as the LU address and session limit (detailed
information). The description of each query_* command indicates whether the command includes the option
of returning summary or detailed information.

For the commands that provide the summary or detailed option, use the list_options parameter to indicate whether
summary or detailed information is required, as well as the starting position within the list. To specify these options,
combine two values with a + character (one value to specify whether summary or detailed information is required,
and one value to specify the starting position in the list), and set the list_options parameter to the combination of
these two values. For example, to specify summary information for all DLCs defined at the node, supply the value
SUMMARY+FIRST_IN_LIST for the list_options parameter on the query_dlc command.

36

Introduction to SNAplus2 Administration Commands

Using snapadmin

To request detailed information, you can use the -d option on the

snapadmin command line instead of specifying a

value of DETAIL for the list_options parameter. The -d option returns detailed information unless you explicitly
specify a value of SUMMARY for the list_options parameter which returns summary information only.

1.1.3 Examples of Administration Commands

This section provides some examples of
of the parameters in these commands are not specified, so
each command in Chapter 2, Administration Commands for details of the default parameter values.

The following commands define connectivity to a remote system over Ethernet. Note the use of angle brackets to
specify the mac_address parameter as a hexadecimal array.

define_ethernet_dlc, dlc_name = DLCNAME, initially_active = YES
define_ethernet_port, port_name = PORTNAME, dlc_name = DLCNAME, initially_active = YES
define_ethernet_ls, ls_name = LSNAME1, port_name = PORTNAME, mac_address = <000000000000>

The following commands define a local LU used for LU6.2, and the partner LU that it communicates with.

define_local_lu, lu_name=LUNAME1, lu_alias=LUNAME1
define_partner_lu, fqplu_name=APPN.PTNRLU, plu_alias=PTNR01

The following command activates a session between the local LU and partner LU, using the standard SNA mode
named #CONNECT. Note the use of a backslash character \ before the # character in this name, to prevent
interpretation by the HP-UX shell.

activate_session, lu_alias=LUNAME1, plu_alias=PTNR01, mode=\#CONNECT

snapadmin

commands as you would issue them on the command line. Many

snapadmin

uses the default values; see the description of

The following commands request information about the definition of the partner LU, its current status, and the
sessions between the local and partner LUs. In all cases, the DETAIL value is used to request detailed information,
overriding the default which is to provide summary information only.

query_partner_lu_definition, list_options=DETAIL, plu_alias=PTNR01
query_partner_lu, list_options=DETAIL, lu_name=LUNAME1, plu_alias=PTNR01
query_session, num_entries=0, list_options=DETAIL+FIRST_IN_LIST, lu_name=LUNAME1, plu_alias=PTNR01

37

Administration Commands

activate_session

2 Administration Commands

This chapter provides reference information about administration commands used for configuring, defining, deleting,
querying, checking status, starting, and stopping the following resources: local nodes, connectivity components,
directory entries, network topology (query only), type 0–3 LUs and pools, 3270 and 5250 users, 3270 domain
resources, and RJE workstations. The commands are listed in alphabetical order.

2.1 activate_session

The activate_session command requests SNAplus2 to activate a session between the local LU and a specified
partner LU, using a specified mode. You must issue an initialize_session_limit command before issuing
an activate_session command unless the

This command must be issued to a running node.

2.1.1 Supplied Parameters

Parameter name Type Length Default
[activate_session]
lu_name character 8 (null string)
lu_alias character 8 (null string)
plu_alias character 8 (null string)
mode_name character 8
fqplu_name character 17 (null string)
polarity constant POL_EITHER
cnos_permitted constant YES

cnos_permitted parameter is set to YES.

Supplied parameters are:

lu_name

LU name of the local LU. This name is a type-A character string. To indicate that the LU is defined by its
LU alias instead of its LU name, do not specify this parameter.

lu_alias

LU alias of the local LU. This alias is a character string using any locally displayable characters. This
parameter is used only if lu_name is not specified.

If lu_name and lu_alias are not specified, the command is forwarded to the LU associated with the CP (the
default LU).

plu_alias

LU alias of the partner LU. This alias is a character string using any locally displayable characters. To
indicate that the partner LU is defined by its fully qualified LU name instead of its LU alias, do not specify
this parameter.

mode_name

Name of the mode to be used by the LUs. This name is a type-A character string starting with a letter.

fqplu_name

Fully qualified name of the partner LU. Specify 3–17 type-A characters that consist of a 1–8 character network
name, followed by a period, followed by a 1–8 character partner LU name.

This parameter is used only if the plu_alias parameter is not specified; it is ignored if plu_alias is specified.

38

Administration Commands

activate_session

polarity

The polarity for the session. Possible values are:

POL_EITHER
POL_FIRST_SPEAKER

POL_BIDDER

If POL_EITHER is set, activate_session activates a first speaker session if available, otherwise a
bidder session is activated. If POL_FIRST_SPEAKER or POL_BIDDER is set, activate_session only
succeeds if a session of the requested polarity is available.

cnos_permitted

Indicates that CNOS processing is permitted. Possible values are:

YES

CNOS processing is permitted.

NO

CNOS processing is not permitted.

If the activation of a new session is not possible because the session limits for the specified mode are reset,
and this parameter is set to YES, implicit CNOS processing will initialize the session limits. Execution of
this command is suspended while CNOS processing is active.

2.1.2 Returned Parameters

If the command executes successfully, the following parameters are returned:

primary_rc

OK

secondary_rc

Possible values are:

AS_NEGOTIATED

The session was activated successfully; the session limit defined for the mode was negotiated during
the activation process.

AS_SPECIFIED

The session was activated successfully; the session limit was not changed.

session_id

The session ID of the new session.

2.1.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

39

Administration Commands

add_backup

Possible values are:

EXCEEDS_MAX_ALLOWED

The session cannot be activated because this would exceed the current session limit for this LU-LU­mode combination.

INVALID_LU_ALIAS

lu_alias parameter did not match any defined local LU alias.

The

INVALID_LU_NAME

The lu_name parameter did not match any defined local LU name.

INVALID_PLU_NAME

The fqplu_name parameter did not match any defined partner LU name, or the plu_alias parameter did
not match any defined partner LU name.

INVALID_CNOS_PERMITTED

The value specified in the cnos_permitted parameter was not valid.

State Check

No specific state errors, other than those listed in Appendix A, Common Return Codes from snapadmin Commands,
occur for this command.

Other Conditions

If the command does not execute because other conditions exist, SNAplus2 returns the following parameters:

primary_rc

ACTIVATION_FAIL_NO_RETRY

The session could not be activated because of a condition that requires action (such as a configuration
mismatch or a session protocol error). Do not retry activating the session. Check the SNAplus2 log
file for information about the error condition and correct it before retrying.

ACTIVATION_FAIL_RETRY

The session could not be activated because of a temporary condition (such as a link failure). Retry,
preferably after a timeout to allow the condition to clear. Check the SNAplus2 log file for information
about the error condition.

secondary_rc

A secondary return code is not returned.

Appendix A, Common Return Codes from snapadmin Commands lists combinations of primary and secondary return
codes that are common to all commands.

2.2 add_backup

The add_backup command adds a server to the list of backup master servers in the sna.net file so this server
can act as the master configuration file server if the current master becomes inactive. The new server is added to
the end of the list; it will only become the master server if all other servers listed in the file are inactive.

This command must be issued without specifying a node name.

2.2.1 Supplied Parameters

Parameter name Type Length
[add_backup]

40

Administration Commands

add_dlc_trace

backup_name character 128

Supplied parameter is:

backup_name

The name of the server to be added to the list of backup servers.

If the server name includes a . (period) character, SNAplus2 assumes that it is a fully-qualified name;
otherwise it performs a DNS lookup to determine the server name.

2.2.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

2.2.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

No parameter errors occur for this command.

State Check

If the command does not execute because of a state error, SNAplus2 returns the following parameters:

primary_rc

STATE_CHECK

secondary_rc

DUPLICATE_RECORD

The server name specified in the backup_name parameter is already listed in the file.

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

2.3 add_dlc_trace

The add_dlc_trace command controls tracing on SNA messages sent on a DLC. It can be used to activate
tracing on a particular DLC, port, LS, or HPR RTP connection. It can also be used to activate tracing on a particular
session on a specified LS or to specify which types of messages are to be traced. The command can also be used
to activate tracing on all DLCs, ports, link stations, and HPR RTP connections. For more information about how
to use SNAplus2 tracing, refer to the HP-UX SNAplus2 Diagnostics Guide.

If multiple add_dlc_trace commands relating to the same resource are issued, a message will be traced if it
matches any of the commands currently active. For example:

• If you issue a command to trace all messages for a port and its link stations and then issue a second command to
trace only messages with a specified LFSID for one of the link stations owned by the port, all messages for the
LS will continue to be traced (because they match the first command). If you then use remove_dlc_trace
to remove tracing for the port, messages on the LS with the specified LFSID will continue to be traced (because
they match the second command which is still active), but other messages on this LS will not be traced.

41

Administration Commands

add_dlc_trace

• If you issue a command to trace XID messages on all resources and then issue a second command to trace SC
and DFC messages on a particular LS, all three message types will be traced for this LS.

If you are tracing an SDLC line and would like more detailed trace information, you can get this by using internal
tracing on SDLC as well as line tracing. The additional detail is formatted as part of the output for line tracing, so
that you will see all of the SDLC tracing in one file. For more information, see Section 2.193,

set_trace_type.

2.3.1 Supplied Parameters

Parameter name Type Length Default
[add_dlc_trace]
resource_type constant ALL_RESOURCES
resource_name character 8 (null string)
sidh hex byte 0
sidl hex byte 0
odai constant NO
message_type constant TRACE_ALL

Supplied parameters are:

resource_type

Specifies the resource to be traced and optionally the specific message types to be traced for this resource.
Possible values are:

ALL_RESOURCES

Specify tracing options for all DLCs, ports, link stations, and RTP connections.

DLC

Specify tracing options for the DLC named in resource_name and for all ports and link stations that
use this DLC.

PORT

Specify tracing options for the port named in resource_name and for all link stations that use this port.

LS

Specify tracing options for the LS named in resource_name.

RTP

Specify tracing options for the RTP connection named in resource_name.

PORT_DEFINED_LS

Specify tracing options for the port named in resource_name and for all defined link stations (but not
implicit link stations) that use this port.

PORT_IMPLICIT_LS

Specify tracing options for the port named in resource_name and for all implicit link stations (but not
defined link stations) that use this port.

resource_name

The name of the DLC, port, LS, or RTP connection for which tracing is to be activated. Do not specify this
parameter if resource_type is set to ALL_RESOURCES.

If resource_type is set to RTP, you can specify the name of a particular RTP connection (this name begins
with the @ character), or you can omit this parameter to indicate that all RTP traffic is to be traced.

The following three parameters identify the Local Form Session Identifier (LFSID) for a session on the specified
LS. These parameters are valid only if resource_type is set to LS, and they indicate that only messages on this
session are to be traced. The LFSID consists of the following parameters:

42

Administration Commands

sidh

Session ID high byte

sidl

Session ID low byte

odai

Origin Destination Assignor Indicator. Possible values are:

YES

The BIND sender is the node containing the secondary link station.

NO

The BIND sender is the node containing the primary link station.

message_type

The type of messages to trace for the specified resource or session. To trace all messages, set this parameter

TRACE_ALL. To trace specific messages, specify one or more of the following values (combined using a

to
+ character):

TRACE_XID

Trace XID messages

add_dlc_trace

TRACE_SC

Trace Session Control Request/Response Units (RUs)

TRACE_DFC

Trace Data Flow Control RUs

TRACE_FMD

Trace Function Management Data messages

TRACE_SEGS

Trace Non-BBIU segments that do not contain an RH

TRACE_CTL

Trace Messages other than MUs and XIDs

TRACE_NLP

Trace Network-Layer Protocol messages

TRACE_NC

Trace Network Control messages

For tracing on an RTP connection, the values TRACE_XID, TRACE_NLP, and TRACE_CTL are ignored. At
least one of the other values listed must be specified for RTP tracing.

2.3.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

2.3.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

43

Administration Commands

aping

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

INVALID_RESOURCE_TYPE

The value specified in the resource_type parameter was not valid.

INVALID_MESSAGE_TYPE

The value specified in the message_type parameter was not valid.

INVALID_RTP_CONNECTION

The resource_name parameter does not match any RTP connection.

State Check

No specific state errors, other than those listed in Appendix A, Common Return Codes from snapadmin Commands,
occur for this command.

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

2.4 aping

The aping command is the APPN version of the “ping” utility and allows a management application to check the
communications path from a local LU to a remote LU in the network.

Instead of using the aping command, you can use the
plication Suite User’s Guide.

SNAplus2 aping is implemented using an internally-defined APPC TP. This TP sends data to the partner LU, and
optionally receives data from the partner LU. If the TP completes successfully, aping returns information about
the time taken to allocate a conversation to the partner LU and to send and receive data.

This command is intended for checking the path to an LU on a remote node. Using aping to check communications
with a partner LU on the local node will impact the performance of other programs on the local computer, and is
not recommended.

This command must be issued to a running node.

2.4.1 Supplied Parameters

APING program described in HP-UX SNAplus2 APPC Ap-

Parameter name Type Length Default
[aping]
lu_name character 8 (null string)
lu_alias character 8 (null string)
plu_alias character 8 (null string)
mode_name character 8
tp_name character 64 APINGD

44

security constant NONE
pwd character 10 (null string)
user_id character 10 (null string)
dlen decimal 0
consec decimal 1
fqplu_name character 17 (null string)
echo constant NO
iterations decimal 0
partner_ver_len decimal 0

Supplied parameters are:

lu_name

Administration Commands

aping

LU name of the local LU. This name is a type-A character string. To indicate that the LU is identi
LU alias instead of its LU name, do not specify this parameter.

lu_alias

LU alias of the local LU. This parameter is used only if

lu_name is not specified. If lu_name and lu_alias

are not specified, the command is forwarded to the LU associated with the CP (the default LU).

plu_alias

Partner LU alias. This parameter should be the alias of an LU on a remote node; using aping with a partner
LU on the local node is not recommended.

To indicate that the LU is identified by its fully qualified name instead of its alias, do not specify this
parameter, but specify the LU name in the fqplu_name parameter.

mode_name

Name of the mode used by the LU pair. This name is a type-A character string starting with a letter.

tp_name

Name of the invoked TP. This parameter is generally set to “APINGD.”

security

Specifies whether conversation security information is required to start the TP. Possible values are:

NONE

No security information is required.

SAME

fied by its

Security information can be verified by the TP that invoked this TP on behalf of a third TP.

PGM

A password and user ID are required to start the TP. The password is sent unencrypted if password
substitution is not supported on the session. If password substitution is supported on the session, the
password is sent encrypted.

PGM_STRONG

A password and user ID are required to start the TP, but the password must not be sent in clear text.
If password substitution is not supported on the session, the aping fails. Otherwise, the password is
sent encrypted.

pwd

Password required to access the partner TP. This parameter is required only if the security parameter is set to
PGM or PGM_STRONG. This password is a type-AE character string.

user_id

45

Administration Commands

aping

User ID required to access the partner TP. This parameter is required only if the security parameter is set to
SAME, PGM or PGM_STRONG. This ID is a type-AE character string.

dlen

Length of the data string to be sent to the partner LU. (You do not need to provide a data string; the APING
TP simply sends a string of zeros of the specified length.) Specify a value in the range 0–65,535.

consec

Number of consecutive data strings sent to the partner LU before a response is required. The APING TP sends
this number of data strings, with each string containing the number of bytes specified by the dlen parameter.
The APING TP then requests either data or a confirmation message from the partner TP, depending on the
setting of the echo parameter. Specify a value in the range 1–65,535.

fqplu_name

Fully qualified name of the partner LU. Specify 3–17 type-A characters that consist of a 1–8 character network
name, followed by a period, followed by a 1–8 character partner LU name.

This name should be the name of an LU on a remote node; using aping with a partner LU on the local
node is not recommended.

This parameter is used only if the plu_alias parameter is not specified; it is ignored if plu_alias is specified.

echo

Specifies whether the APING TP receives data or requests confirmation from the partner LU after sending
data to it. Possible values are:

YES

After sending the specified number of data strings, the APING TP receives data from the partner LU.

NO

After sending the specified number of data strings, the APING TP requests confirmation from the
partner LU, but does not receive data.

iterations

Number of times that the APING TP performs the sequence of sending data to the partner LU and requesting
either data or confirmation. Specify a value in the range 0–65,535.

partner_ver_len

Maximum length of the partner TP verification data string to return. Specify a value in the range 0–3000.

2.4.2 Returned Parameters

Parameter name Type Length
alloc_time decimal
min_time decimal
avg_time decimal
max_time decimal
partner_ver_len decimal
partner_ver_data hex array (max_length as specified on command)

If the command executes successfully, SNAplus2 returns the following parameters:

alloc_time

The time in milliseconds to allocate a conversation to the partner—the time taken for the MC_ALLOCATE
verb issued by the APING TP to complete.

min_time

46

Administration Commands

The minimum time in milliseconds required for a data-sending iteration—the shortest measured time for a
single iteration of sending data and receiving either data or confirmation. If

iterations was set to 0 (zero),

this parameter is not used.

avg_time

The average time in milliseconds required for a data-sending iteration—the average time for a single iteration
of sending data and receiving either data or confirmation. If iterations was set to 0 (zero), this parameter is
not used.

max_time

The maximum time in milliseconds required for a data-sending iteration—the longest measured time for a
single iteration of sending data and receiving either data or confirmation. If iterations was set to 0 (zero),
this parameter is not used.

partner_ver_len

Actual length of the verification string returned by the partner TP.

partner_ver_data

Verification string returned by the partner TP. If partner_ver_len is 0 (zero), then this string is not returned.

2.4.3 Error Return Codes

aping

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

INVALID_LU_ALIAS

The lu_alias parameter value did not match any defined LU alias.

INVALID_LU_NAME

The lu_name parameter value did not match any defined LU name.

BAD_PARTNER_LU_ALIAS

The value specified for plu_alias did not match any defined partner LU.

State Check

No specific state errors, other than those listed in Appendix A, Common Return Codes from snapadmin Commands,
occur for this command.

Other Conditions

If the command does not execute because other conditions exist, SNAplus2 returns the following parameters:

primary_rc

ALLOCATION_ERROR

SNAplus2 could not allocate the APPC conversation with the remote TP.

secondary_rc

47

Administration Commands

aping

Possible values are:

ALLOCATION_FAILURE_NO_RETRY

The conversation could not be allocated because of a permanent condition, such as a configuration error
or session protocol error. Check the
Do not attempt to retry the aping command until the error has been corrected.

ALLOCATION_FAILURE_RETRY

The conversation could not be allocated because of a temporary condition, such as a link failure. Check
the error log file for more information. Retry the aping command, preferably after a timeout to allow
the condition to clear.

SECURITY_NOT_VALID

The user ID or password specified was not accepted by the partner LU.

TP_NAME_NOT_RECOGNIZED

The partner LU does not recognize the specified TP name.

TRANS_PGM_NOT_AVAIL_NO_RETRY

The remote LU rejected the allocation request because it was unable to start the requested partner TP.
The condition is permanent. The reason for the error may be logged on the remote node. Do not retry
the aping command until the cause of the error has been corrected.

TRANS_PGM_NOT_AVAIL_RETRY

sense_data parameter and the error log file for more information.

The remote LU rejected the allocation request because it was unable to start the requested partner TP.
The condition may be temporary, such as a timeout. The reason for the error may be logged on the
remote node. Retry the aping command, preferably after a timeout to allow the condition to clear.

sense_data

If the secondary_rc parameter is

ALLOCATION_FAILURE_NO_RETRY, this parameter contains the SNA sense

data associated with the error. For all other secondary_rc values, this parameter is not returned.

primary_rc

CONV_FAILURE_NO_RETRY

The APPC conversation with the partner TP was terminated because of a permanent condition, such as
a session protocol error. Check the error log file to determine the cause of the error. Do not retry the
aping command until the error has been corrected.

primary_rc

CONV_FAILURE_RETRY

The APPC conversation with the partner TP was terminated because of a temporary error. Retry the
aping command. If the problem occurs again, check the error log file to determine the cause of the
error.

primary_rc

DEALLOC_ABEND

The partner TP deallocated the APPC conversation because of an error condition. The reason for the
error may be logged on the remote node.

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

48

Administration Commands

change_session_limit

2.5 change_session_limit

The change_session_limit command requests SNAplus2 to change the session limits for a particular LU­LU-mode combination. Sessions can be activated or deactivated as a result of processing this command.

This command must be issued to a running node.

2.5.1 Supplied Parameters

Parameter name Type Length Default
[change_session_limit]
lu_name character 8 (null string)
lu_alias character 8 (null string)
plu_alias character 8 (null string)
fqplu_name character 17 (null string)
mode_name character 8
set_negotiable constant NO
plu_mode_session_limit decimal
min_conwinners_source decimal 0
min_conwinners_target decimal 0
auto_act decimal 0
responsible constant SOURCE

Supplied parameters are:

lu_name

LU name of the local LU. This name is a type-A character string. To indicate that the LU is defined by its
LU alias instead of its LU name, do not specify this parameter.

lu_alias

LU alias of the local LU. This alias is a character string using any locally displayable characters. It is used
only if

lu_name is not specified.

If lu_name and lu_alias are not specified, the command is forwarded to the LU associated with the CP (the
default LU).

plu_alias

LU alias of the partner LU. This alias is a character string using any locally displayable characters. To
indicate that the partner LU is defined by its fully qualified LU name instead of its LU alias, do not specify
this parameter.

fqplu_name

Fully qualified name of the partner LU. Specify 3–17 type-A characters that consist of a 1–8 character network
name, followed by a period, followed by a 1–8 character partner LU name.

This parameter is used only if the plu_alias parameter is not specified; it is ignored if plu_alias is specified.

mode_name

Name of the mode to be used by the LUs. This name is a type-A character string starting with a letter.

set_negotiable

Specifies whether the maximum negotiable session limit for this mode, as defined by define_mode, should
be modified. Possible values are:

YES

Use the value specified by plu_mode_session_limit as the maximum negotiable session limit for this
LU-LU-mode combination.

49

Administration Commands

change_session_limit

NO

Leave the maximum negotiable session limit as the value specified for the mode.

plu_mode_session_limit

Requested total session limit for this LU-LU-mode combination—the maximum number of parallel sessions
allowed between these two LUs using this mode. This value can be negotiated with the partner LU. Specify
a value in the range

1–32,767 (which must not exceed the session limit specified for the local LU on

the define_local_lu command). To specify a value of 0 (zero) use the reset_session_limit
command.

min_conwinners_source

Minimum number of sessions using this mode for which the local LU is the contention winner. The sum of the
min_conwinners_source and min_conwinners_target parameters must not exceed the plu_mode_session_limit
parameter. Specify a value in the range 0–32,767.

min_conwinners_target

Minimum number of sessions using this mode for which the partner LU is the contention winner.
The sum of the min_conwinners_source and min_conwinners_target parameters must not exceed the
plu_mode_session_limit parameter. Specify a value in the range 0–32,767.

auto_act

Number of sessions to activate automatically after the session limit is changed. The actual number
of automatically activated sessions is the minimum of this value and the negotiated minimum number
of contention winner sessions for the local LU. When sessions are deactivated normally (specifying
DEACT_NORMAL for the type parameter on deactivate_session) this limit, new sessions are activated
up to this limit. Specify a value in the range 0–32,767 (which must not exceed the plu_mode_session_limit
parameter or the session limit specified for the local LU on the define_local_lu command).

responsible

Indicates whether the local LU or partner LU is responsible for deactivating sessions after the session limit
is changed. Possible values are:

SOURCE

The local LU is responsible for deactivating sessions after the session limit has been changed.

TARGET

The partner LU is responsible for deactivating sessions after the session limit has been changed.

2.5.2 Returned Parameters

If the command executes successfully, the following parameters are returned:

primary_rc

OK

secondary_rc

Possible values are:

AS_NEGOTIATED

AS_SPECIFIED

50

The session limits were changed, but one or more values were negotiated by the partner LU.

The session limits were changed as requested, without being negotiated by the partner LU.

Administration Commands

change_session_limit

2.5.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

EXCEEDS_MAX_ALLOWED

The plu_mode_session_limit, min_conwinners_source, min_conwinners_target,orauto_act parameter
was set to a value outside the valid range.

CANT_CHANGE_TO_ZERO

The plu_mode_session_limit parameter cannot be set to
reset_session_limit command instead.

INVALID_LU_ALIAS

The lu_alias parameter did not match any defined local LU alias.

INVALID_LU_NAME

The lu_name parameter did not match any defined local LU name.

INVALID_MODE_NAME

The mode_name parameter did not match any defined mode name.

INVALID_PLU_NAME

The fqplu_name parameter did not match any defined partner LU name.

INVALID_RESPONSIBLE

The responsible parameter was not set to a valid value.

INVALID_SET_NEGOTIABLE

The set_negotiable parameter was not set to a valid value.

0 (zero) using this command; use the

State Check

If the command does not execute because of a state error, SNAplus2 returns the following parameters:

primary_rc

STATE_CHECK

secondary_rc

MODE_RESET

No sessions are currently active for this LU-LU-mode combination. Use initial­ize_session_limit instead of change_session_limit to specify the limits.

Other Conditions

If the command does not execute because other conditions exist, SNAplus2 returns the following parameters:

primary_rc

ALLOCATION_ERROR

secondary_rc

51

Administration Commands

deactivate_conv_group

ALLOCATION_FAILURE_NO_RETRY

A session could not be allocated because of a condition that requires action. Check the sense_data
parameter and logged messages to determine the reason for the failure, and take any action required.
Do not attempt to retry the command until the condition has been corrected.

sense_data

If the secondary_rc parameter is

ALLOCATION_FAILURE_NO_RETRY

, this parameter contains the SNA sense

data associated with the error. For all other secondary_rc values, this parameter is not returned.

primary_rc

CONV_FAILURE_NO_RETRY

The session limits could not be initialized because of a condition that requires action (such as a
configuration mismatch or a session protocol error). Check the SNAplus2 log file for information about
the error condition, and correct it before retrying this command.

primary_rc

CNOS_PARTNER_LU_REJECT

secondary_rc

CNOS_COMMAND_RACE_REJECT

The command failed because the specified mode was being accessed by another administration program
(or internally by the SNAplus2 software) for session activation or deactivation, or for session limit
processing. Retry the command.

Appendix A, Common Return Codes from snapadmin Commands lists combinations of primary and secondary return
codes that are common to all commands.

2.6 deactivate_conv_group

The deactivate_conv_group command requests SNAplus2 to deactivate the session corresponding to the
specified APPC conversation group. Although this command is available within the command-line administration
program, deactivating a session identified by its conversation group is more usually done using the NOF verb
DEACTIVATE_CONV_GROUP from within an APPC TP. The conversation group identifier is returned by the
APPC verbs [MC_]ALLOCATE, [MC_]GET_ATTRIBUTES, and RECEIVE_ALLOCATE.

This command must be issued to a running node.

2.6.1 Supplied Parameters

Parameter name Type Length Default
[deactivate_conv_group]
lu_name character 8 (null string)
lu_alias character 8 (null string)
conv_group_id decimal
type constant DEACT_NORMAL
sense_data hex number 4 0x0

Supplied parameters are:

lu_name

LU name of the local LU. This name is a type-A character string. To indicate that the LU is defined by its
LU alias instead of its LU name, do not specify this parameter.

52

Administration Commands

deactivate_conv_group

lu_alias

LU alias of the local LU. This alias is a character string using any locally displayable characters. This
parameter is used only if

lu_name is not specified.

If lu_name and lu_alias are not specified, the command is forwarded to the LU associated with the CP (the
default LU).

conv_group_id

Conversation group identifier for the session to be deactivated.

type

Type of deactivation. Possible values are:

DEACT_CLEANUP

Deactivate the session immediately, without waiting for a response from the partner LU.

DEACT_NORMAL

Do not deactivate the session until all conversations using the session have ended.

sense_data

If type is set to DEACT_CLEANUP, the sense_data parameter specifies the sense data to be used
when deactivating the session (specified as a 4-byte hexadecimal number preceded by 0x, for example
0x84000007). Otherwise, this parameter is not used.

2.6.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

2.6.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

DEACT_CG_INVALID_CGID

The conv_group_id parameter did not match any valid conversation group ID.

INVALID_CLEANUP_TYPE

The type parameter was not set to a valid value.

INVALID_LU_ALIAS

The lu_alias parameter did not match any defined LU alias.

INVALID_LU_NAME

The lu_name parameter did not match any defined LU name.

53

Administration Commands

deactivate_lu_0_to_3

State Check

No specific state errors, other than those listed in Appendix A, Common Return Codes from snapadmin Commands,
occur for this command.

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

2.7 deactivate_lu_0_to_3

The deactivate_lu_0_to_3 command requests SNAplus2 to deactivate the session for a particular LU for
use with 3270 emulation, RJE or LUA (an LU of type 0, 1, 2, or 3). SNAplus2 deactivates the session by sending
a TERM_SELF message to the host for the PLU-SLU session.

This command must be issued to a running node.

2.7.1 Supplied Parameters

Parameter name Type Length Default
[deactivate_lu_0_to_3]
lu_name character 8

Supplied parameters are:

lu_name

LU name of the local LU. This name is a type-A character string.

2.7.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

2.7.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

INVALID_LU_NAME

The lu_name parameter did not match any defined LU name.

State Check

No specific state errors, other than those listed in Appendix A, Common Return Codes from snapadmin Commands,
occur for this command.

54

Administration Commands

deactivate_session

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

2.8 deactivate_session

The deactivate_session command requests SNAplus2 to deactivate one or more sessions using a particular
local LU/mode/partner LU combination.

To identify a local LU/mode/partner LU combination specify the following:

• Specify the local LU using either the lu_name or the lu_alias parameter. If neither are specified then the LU
associated with the CP (the default LU) is used.

• Specify the mode.

• Specify the remote LU using either the fqplu_name or the plu_alias parameter.

To deactivate a particular session using the specified local LU/mode/partner LU combination, specify its session
identifier. If no session identifier is specified then all sessions using the specified local LU/mode/partner LU are
deactivated.

This command must be issued to a running node.

2.8.1 Supplied Parameters

Parameter name Type Length Default
[deactivate_session]
lu_name character 8 (null string)
lu_alias character 8 (null string)
session_id hex number 8 0x0
plu_alias character 8 (null string)
mode_name character 8
type constant DEACT_NORMAL
sense_data hex number 4 0x0
fqplu_name character 17 (null string)

Supplied parameters are:

lu_name

LU name of the local LU. This name is a type-A character string. To indicate that the LU is defined by its
LU alias instead of its LU name, do not specify this parameter.

lu_alias

LU alias of the local LU. This alias is a character string using any locally displayable characters. This
parameter is used only if lu_name is not specified.

If lu_name and lu_alias are not specified, the command is forwarded to the LU associated with the CP (the
default LU).

session_id

An 8-byte identifier of the session to deactivate. If you do not specify this parameter, SNAplus2 deactivates
all sessions for the LU-MODE-LU combination.

An error code is not returned when the specified session ID does not match the session ID of an active session
(implying that the session has already been deactivated).

55

Administration Commands

deactivate_session

plu_alias

LU alias of the partner LU. This alias is a character string using any locally displayable characters. To
indicate that the partner LU is defined by its fully qualified LU name instead of its LU alias, do not specify
this parameter.

mode_name

Name of the mode to be used by the LUs. This name is a type-A character string starting with a letter.

type

Type of deactivation. Possible values are:

DEACT_CLEANUP

Deactivate the session immediately, without waiting for a response from the partner LU.

DEACT_NORMAL

Do not deactivate the session until all conversations using the session have ended.

sense_data

If type is set to DEACT_CLEANUP, the sense_data parameter specifies the sense data to be used
when deactivating the session (specified as a 4-byte hexadecimal number preceded by 0x, for example
0x84000007). Otherwise, this parameter is not used.

fqplu_name

Fully qualified name of the partner LU. Specify 3–17 type-A characters that consist of a 1–8 character network
name, followed by a period, followed by a 1–8 character partner LU name.

This parameter is used only if the plu_alias parameter is not specified; it is ignored if plu_alias is specified.

2.8.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

2.8.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

INVALID_CLEANUP_TYPE

INVALID_LU_ALIAS

INVALID_LU_NAME

56

The type parameter was not set to a valid value.

The lu_alias parameter did not match any defined LU alias.

The lu_name parameter did not match any defined LU name.

Administration Commands

define_3270_diag

INVALID_MODE_NAME

The mode_name parameter did not match any defined mode name.

INVALID_PLU_NAME

The fqplu_name parameter did not match any defined partner LU name.

State Check

No specific state errors, other than those listed in Appendix A, Common Return Codes from snapadmin Commands,
occur for this command.

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

2.9 define_3270_diag

The define_3270_diag command specifies the 3270 diagnostics parameters for the SNAplus2 system, such as
the parameters used to record and display response-time data and the 3270 user alerts that users can send to the
host NetView program. The command can be used to define 3270 diagnostics parameters for the first time or to
modify an existing definition.

This command is not associated with a particular node because the 3270 diagnostics parameters are defined as
domain resources.

2.9.1 Supplied Parameters

Parameter name Type Length Default
[define_3270_diag]
rtm_overflow constant NO
rtm_unbind constant NO
rtm_timer_option constant RTM_SCREEN
rtm_thresh1 decimal 0.5
rtm_thresh2 decimal 1.0
rtm_thresh3 decimal 2.0
rtm_thresh4 decimal 5.0

{alert_3270_data}
description character 53 (null string)
parameter1 character 33 (null string)
parameter2 character 33 (null string)
parameter3 character 33 (null string)

(You can include 0–20 alert_3270_data subrecords.)

Supplied parameters are:

rtm_overflow

Specifies whether to send RTM data to the host every time one of the RTM counters overflows (reaches its
maximum value). There is a counter for each of the intervals defined by the rtm_thresh values. Possible
values are:

YES

57

Administration Commands

define_3270_diag

Send RTM data to the host every time a counter overflows.

NO

Do not send RTM data to the host at counter overflow. SNAplus2 discards the RTM data.

rtm_unbind

Specifies whether to send RTM data to the host every time a 3270 session is unbound (ends). Possible values
are:

YES

Send RTM data to the host every time a session ends.

NO

Do not send RTM data to the host at session end. SNAplus2 discards the RTM data.

rtm_timer_option

Specifies how the host response time is measured. The response time is measured by the interval between
the user pressing

[ENTER]

or other AID key to send data to the host, and one of the following events:

RTM_SCREEN

The first data from the host reaches the user’s screen

RTM_UNLOCK

The host unlocks the user’s keyboard

RTM_DIRECTION

The host gives the 3270 emulation program direction, so that the user can send more data

rtm_thresh1 through rtm_thresh4

Specifies the threshold values used to classify response times. These values divide the range of possible
response times into five intervals as follows: below rtm_thresh1, between rtm_thresh1 and rtm_thresh2, be­tween rtm_thresh2 and rtm_thresh3, between rtm_thresh3 and rtm_thresh4, and above rtm_thresh4. SNAplus2
maintains a counter for each of these intervals. Each time a host response is received, SNAplus2 determines
which of these intervals the response falls into and increments the appropriate counter.

For each threshold, specify a number in seconds and optionally tenths of seconds (

2 for 2 seconds or 2.5 for

2.5 seconds). The values must be in the range 0.1–100 seconds, and must be in ascending order (rtm_thresh2
must be higher than rtm_thresh1, rtm_thresh3 must be higher than rtm_thresh2, and so on).

alert_3270_data

subrecords

The host NetView program identifies each alert by a number in the range 1–20; consult the NetView
administrator for the host to determine which alert numbers are used and the meaning of each alert. The

alert_3270_data subrecords supplied to this command are assigned to these numbers in sequence (the first

subrecord is assigned to alert number 1, the second subrecord to alert number 2, and so on). If the host
does not use all the alert numbers in the range, include a blank alert subrecord (including only the subrecord
descriptor with no parameters specified) for each unused number. For example, if the host uses only alert
numbers 10 and 11, include nine blank alert subrecords followed by the subrecords for alerts 10 and 11.

You can include 0–20

For each alert, an

alert_3270_data subrecords.

alert_3270_data subrecord is required with the following information:

description

A text description of the alert. This description is a string of 1–53 characters.

This description is displayed in the 3270 user interface to identify the alert to the user. It is not sent to
NetView; the NetView operator identifies the alert by its number.

58

Administration Commands

define_adjacent_len_node

parameter1 through parameter3

Text strings describing any parameters that the user should enter for the alert. Each one is a string of 1
characters.

Consult the NetView administrator for the host to determine the parameters required for each alert. An alert
may not require all three parameters; do not specify any parameters that are not required. The user will only
be prompted for a parameter if you specify a description for it.

–33

2.9.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

2.9.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

INVALID_RTM_THRESHOLD

One or more of the supplied RTM threshold values was not in the valid range, or the values were not
in ascending order.

State Check

No specific state errors, other than those listed in Appendix A, Common Return Codes from snapadmin Commands,
occur for this command.

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

2.10 define_adjacent_len_node

define_adjacent_len_node adds entries to the node directory database for an adjacent LEN node and its
associated LUs, or adds additional LU entries for a previously-defined LEN node.

This command is equivalent to a series of define_directory_entry commands for the LEN node and its
associated LUs; it provides a fast method of defining the LEN node’s configuration with a single command. To
query the directory entries created by this command, use query_directory_entry.

If this command is issued to the network node acting as the server for the LEN node, the LEN node’s resources
are added to the network node’s directory database. This means that the network node will respond to network
searches for these resources, so that they are accessible to the entire network.

If the command is issued to an end node, the LEN node’s resources are accessible only to that end node.

59

Administration Commands

define_adjacent_len_node

2.10.1 Supplied Parameters

Parameter name Type Length Default
[define_adjacent_len_node]
cp_name character 17
description character 31 (null string)
lu_name character 8
wildcard_lus constant NO

(Up to 10 lu_name entries may be included.)

Supplied parameters are:

cp_name

The fully qualified name of the CP in the adjacent LEN end node. This name should match the name the
LEN node sends on its XIDs (if the LEN node supports XIDs) and the adjacent CP name specified on the
define_ls command for the link to the LEN node.

Specify 3–17 characters that consist of a 1–8 character network name, followed by a period, followed by a
1–8 character partner LU name.

description

A text string of 0–31 characters followed by a null character that describes the adjacent node. SNAplus2
uses this string for information only. It is stored in the node’s configuration file and returned on the
query_directory_entry command.

lu_name

Name of an LU defined on the LEN node. Specify 1–8 type-A characters corresponding to the second part of
the fully qualified LU name (the first part of the fully-qualified name is defined by the cp_name parameter).

To de fine an adjacent node with more than 10 LUs, use multiple define_adjacent_len_node
commands for the same CP name.

To d efine the LU associated with the LEN node’s control point (the CP LU or default LU), specify the node’s
fully qualified CP name in the cp_name parameter, and include the ’network name’ part of this name (the 8
characters after the period) as one of the LU names.

You can specify a ’wildcard’ LU name to match multiple LU names by specifying only the initial characters
of the name. For example, the wildcard LU name LU will match LUNAME or LU01 (but will not match
NAMELU). However, all the LU names specified on a single command must be of the same type (wildcard
or explicit), as defined by the wildcard_lus parameter. To add both types of LU names for the same adjacent
node, use multiple define_adjacent_len_node commands.

wildcard_lus

Indicates whether the specified LU names are wildcard entries or explicit LU names. Possible values are:

YES

The specified LU names are wildcard entries.

NO

The specified LU names are explicit entries.

2.10.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

2.10.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

60

Administration Commands

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

INVALID_CP_NAME

The cp_name parameter contained a character that was not valid.

INVALID_LU_NAME

One or more of the specified LU names contained a character that was not valid.

INVALID_WILDCARD_NAME

The wildcard_lus parameter was set to

YES, but one or more of the specified LU names was already

defined on a different parent node.

State Check

If the command does not execute because of a state error, SNAplus2 returns the following parameters:

primary_rc

STATE_CHECK

secondary_rc

Possible values are:

INVALID_CP_NAME

The CP name specified by the cp_name parameter was already defined in a directory entry and is not
a LEN node.

INVALID_LU_NAME

One or more of the LU names specified by the lu_name parameter were already defined on a different
parent node.

define_cn

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

2.11 define_cn

The define_cn command defines a connection network (also known as a virtual routing node or VRN). The
command provides the network qualified name of the connection network along with its Transmission Group (TG)
characteristics. Also provided is a list of the names of the local ports that can access this connection network.

This command can also be used to add new ports to an existing connection network. (Ports can be removed from
an existing connection network by issuing delete_cn.)

This command is valid only at a network node or an end node, and not at a LEN node.

2.11.1 Supplied Parameters

Parameter name Type Length Default
[define_cn]

61

Administration Commands

define_cn

fqcn_name character 17
description character 32 (null string)
effect_cap decimal 3686400
connect_cost decimal 0
byte_cost decimal 0
security constant SEC_NONSECURE
prop_delay constant PROP_DELAY_LAN
user_def_parm_1 decimal 0
user_def_parm_2 decimal 0
user_def_parm_3 decimal 0
port_name character 8 (null string)

(1–239 port_name entries can be included)

Supplied parameters are:

fqcn_name

Fully qualified name of the connection network. Specify 3–17 type-A characters that consist of a 1–8 character
network name, followed by a period, and followed by a 1–8 character connection network name.

description

A text string describing the connection network. SNAplus2 uses this string for information only. It is stored
in the node’s configuration file and returned on the

query_cn command.

effect_cap

A decimal value representing the line speed in bits per second.

connect_cost

Cost per connect time. Valid values are integer values in the range 0–255, where 0 is the lowest cost per
connect time and 255 is the highest cost per connect time.

byte_cost

Cost per byte. Valid values are integer values in the range 0–255, where 0 is the lowest cost per byte and
255 is the highest cost per byte.

security

Security level of the network. Possible values are:

SEC_NONSECURE

No security.

SEC_PUBLIC_SWITCHED_NETWORK

Data is transmitted over a public switched network.

SEC_UNDERGROUND_CABLE

Data is transmitted over secure underground cable.

SEC_SECURE_CONDUIT

Data is transmitted over a line in a secure conduit that is not guarded.

SEC_GUARDED_CONDUIT

Data is transmitted over a line in a conduit that is protected against physical tapping.

SEC_ENCRYPTED

Data is encrypted before transmission over the line.

SEC_GUARDED_RADIATION

62

Administration Commands

Data is transmitted over a line that is protected against physical and radiation tapping.

prop_delay

Propagation delay. The time that a signal takes to travel the length of the link. Specify one of the following
values, according to the type of link:

PROP_DELAY_MINIMUM

Minimum propagation delay.

PROP_DELAY_LAN

Delay is less than .5 microseconds (typical for a LAN).

PROP_DELAY_TELEPHONE

Delay is in the range .5–50 microseconds (typical for a telephone network).

PROP_DELAY_PKT_SWITCHED_NET

Delay is in the range 50–250 microseconds (typical for a packet-switched network).

PROP_DELAY_SATELLITE

Delay is greater than 250 microseconds (typical for a satellite link).

PROP_DELAY_MAXIMUM

Maximum propagation delay.

define_cn

user_def_parm_1 through user_def_parm_3

User-defined parameters, which you can use to include other characteristics not covered by the previous
parameters. Each of these parameters must be set to a value in the range 0–255.

port_name

Array of port names defined on the connection network. Each port name is an 8-byte string consisting of lo­cally displayable characters that must match the name of a previously-defined port. The port type must be a
network type that supports connection networks (Ethernet, Token Ring, FDDI, Enterprise Extender).

fqcn_name parameter identifies an existing connection network, the new ports are added to it (without

If the
changing any ports already defined on the connection network).

2.11.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

2.11.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

DEF_LINK_INVALID_SECURITY

63

Administration Commands

define_cos

The security parameter was not set to one of the valid values.

EXCEEDS_MAX_ALLOWED

Adding the specified ports would exceed the maximum total number of ports on a CN.

INVALID_CN_NAME

The fqcn_name parameter contained a character that was not valid or was not in the correct format.

INVALID_PORT_NAME

One or more of the port names specified did not match the name of a defined port.

INVALID_PORT_TYPE

One or more of the specified ports cannot be on a CN because its DLC type is a point-to-point type
(such as SDLC) rather than a network type.

State Check

If the command does not execute because of a state error, SNAplus2 returns the following parameters:

primary_rc

STATE_CHECK

secondary_rc

PORT_ACTIVE

The port specified by the port_name parameter cannot be modified because it is currently active.

Function Not Supported

If the command does not execute because the node’s configuration does not support it, SNAplus2 returns the
following parameters:

primary_rc

FUNCTION_NOT_SUPPORTED

The local node is a LEN node. This command is valid only at a network node or an end node.

secondary_rc

(This parameter is not used.)

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

2.12 define_cos

The define_cos command adds a class of service (COS) definition or modifies a previously defined COS. The
definition specifies TG “rows” and node “rows”, which associate a range of node and TG characteristics with
weights that are used for route calculation. The lower the weight the more favorable the route.

2.12.1 Supplied Parameters

Parameter name Type Length Default
[define_cos]
cos_name character 8

64

Administration Commands

description character 31 (null string)
transmission_priority constant LOW

{cos_tg_row}
min_effect_cap decimal 0
min_connect_cost decimal 0
min_byte_cost decimal 0
min_security constant SEC_NONSECURE
min_prop_delay constant PROP_DELAY_LAN
min_user_def_parm_1 decimal 0
min_user_def_parm_2 decimal 0
min_user_def_parm_3 decimal 0
max_effect_cap hex 1 0xFF
max_connect_cost decimal 255
max_byte_cost decimal 255
max_security constant SEC_GUARDED_RADIATION
max_prop_delay constant PROP_DELAY_MAXIMUM
max_user_def_parm_1 decimal 0
max_user_def_parm_2 decimal 0
max_user_def_parm_3 decimal 0
weight decimal

define_cos

(Up to eight

{cos_node_row}
min_rar decimal 0
min_status constant UNCONGESTED
max_rar decimal 255
max_status constant CONGESTED
weight decimal

(Up to eight

cos_tg_row subrecords can be included, in ascending order of weight.)

cos_node_row subrecords can be included, in ascending order of weight.)

Supplied parameters are:

cos_name

Class of service name. This name is a type-A character string starting with a letter.

description

A text string describing the COS. SNAplus2 uses this string for information only. It is stored in the node’s
configuration file and returned on the

query_cos command.

transmission_priority

Transmission priority. Possible values are:

LOW

The session using this COS is given low priority.

MEDIUM

The session using this COS is given medium priority.

HIGH

The session using this COS is given high priority.

NETWORK

The session using this COS is given the highest priority.

The following subrecord contains additional parameters:

cos_tg_row

Each TG row contains a set of minimum TG characteristics, a set of maximum TG characteristics, and a
weight. When computing the weights for a TG, its characteristics are checked against the minimum and

65

Administration Commands

define_cos

maximum characteristics defined for each TG row. The TG is then assigned the weight of the first TG row
which bounds all the TG’s characteristics within the limits specified. If the TG characteristics do not satisfy
any of the listed TG rows, the TG is considered unsuitable for this COS, and is assigned an infinite weight.
The TG rows must be listed in ascending order of weight.

The additional parameters are:

min_effect_cap

Minimum limit for actual bits per second rate (line speed).

min_connect_cost

Minimum limit for cost per connect time. Valid values are integer values in the range 0–255, where
0 is the lowest cost per connect time and 255 is the highest cost per connect time.

min_byte_cost

Minimum limit for cost per byte. Valid values are integer values in the range 0–255, where 0 is the
lowest cost per byte and 255 is the highest cost per byte.

min_security

Minimum level of security. Possible values are:

SEC_NONSECURE

Data is transmitted over an unsecured network.

SEC_PUBLIC_SWITCHED_NETWORK

Data is transmitted over a public-switched network.

SEC_UNDERGROUND_CABLE

Data is transmitted over secure underground cable.

SEC_SECURE_CONDUIT

Data is transmitted over a line in a secure conduit that is not guarded.

SEC_GUARDED_CONDUIT

Data is transmitted over a line in a conduit that is protected against physical tapping.

SEC_ENCRYPTED

Data is encrypted before transmission over the line.

SEC_GUARDED_RADIATION

Data is transmitted over a line that is protected against physical and radiation tapping.

min_prop_delay

Minimum limits for propagation delay, which is the time that a signal takes to travel the length of the
link. Specify one of the following values, according to the type of link:

PROP_DELAY_MINIMUM

66

Minimum propagation delay.

PROP_DELAY_LAN

Delay is less than .5 microseconds (typical for a LAN).

PROP_DELAY_TELEPHONE

Delay is in the range .5–50 microseconds (typical for a telephone network).

Administration Commands

PROP_DELAY_PKT_SWITCHED_NET

Delay is in the range 50–250 microseconds (typical for a packet-switched network).

PROP_DELAY_SATELLITE

Delay is greater than 250 microseconds (typical for a satellite link).

PROP_DELAY_MAXIMUM

Maximum propagation delay.

min_user_def_parm_1 through min_user_def_parm_3

Minimum limits for user-defined parameters, which you can use to include TG characteristics not
covered by previously defined parameters. Each of these parameters must be set to a value in the range
0–255.

max_effect_cap

Maximum limit for actual bits per second rate (line speed). Specify a value in the range 0–
603,979,776,000.

max_connect_cost

Maximum limit for cost per connect time. Valid values are integer values in the range 0–255, where
0 is the lowest cost per connect time and 255 is the highest cost per connect time.

define_cos

max_byte_cost

Maximum limit for cost per byte. Valid values are integer values in the range 0–255, where 0 is the
lowest cost per byte and 255 is the highest cost per byte.

max_security

Maximum level of security. Possible values are:

SEC_NONSECURE

Data is transmitted over an unsecured network.

SEC_PUBLIC_SWITCHED_NETWORK

Data is transmitted over a public-switched network.

SEC_UNDERGROUND_CABLE

Data is transmitted over secure underground cable.

SEC_SECURE_CONDUIT

Data is transmitted over a line in a secure conduit that is not guarded.

SEC_GUARDED_CONDUIT

Data is transmitted over a line in a conduit that is protected against physical tapping.

SEC_ENCRYPTED

Data is encrypted before transmission over the line.

SEC_GUARDED_RADIATION

Data is transmitted over a line that is protected against physical and radiation tapping.

max_prop_delay

Maximum limits for propagation delay, which is the time that a signal takes to travel the length of the
link. Specify one of the following values, according to the type of link:

67

Administration Commands

define_cos

PROP_DELAY_MINIMUM

Minimum propagation delay.

PROP_DELAY_LAN

Delay is less than .5 microseconds (typical for a LAN).

PROP_DELAY_TELEPHONE

Delay is in the range .5–50 microseconds (typical for a telephone network).

PROP_DELAY_PKT_SWITCHED_NET

Delay is in the range 50–250 microseconds (typical for a packet-switched network).

PROP_DELAY_SATELLITE

Delay is greater than 250 microseconds (typical for a satellite link).

PROP_DELAY_MAXIMUM

Maximum propagation delay.

max_user_def_parm_1 through max_user_def_parm_3

Maximum limits for user-defined parameters, which you can use to include TG characteristics not
covered by previously described parameters. Each of these parameters must be set to a value in the

0–255.

range

weight

Weight associated with this TG row.

The following subrecord contains additional parameters:

cos_node_row

Each node row contains a set of minimum node characteristics, a set of maximum node characteristics, and
a weight. When computing the weights for a node, its characteristics are checked against the minimum and
maximum characteristics defined for each node row. The node is then assigned the weight of the first node
row which bounds all the node’s characteristics within the limits specified. If the node characteristics do not
satisfy any of the listed node rows, the node is considered unsuitable for this COS, and is assigned an infinite
weight. The node rows must be listed in ascending order of weight.

The additional parameters are:

min_rar

Specifies the minimum route additional resistance (RAR). Values must be in the range 0–255.

min_status

Specifies the minimum congestion status of the node. Possible values are:

UNCONGESTED

The number of ISR sessions is less than the isr_sessions_upper_threshold value in the node’s
configuration.

CONGESTED

The number of ISR sessions exceeds the isr_sessions_upper_threshold value.

max_rar

Specifies the maximum route additional resistance (RAR). Values must be in the range 0–255.

max_status

Specifies the maximum congestion status of the node. Possible values are:

68

Administration Commands

define_cos

UNCONGESTED

The number of ISR sessions is less than the isr_sessions_upper_threshold value in the node’s
configuration.

CONGESTED

The number of ISR sessions exceeds the isr_sessions_upper_threshold value.

weight

Weight associated with this node row.

2.12.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

2.12.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

INVALID_COS_NAME

The cos_name parameter contained a character that was not valid.

INVALID_NUMBER_OF_NODE_ROWS

Too many node rows were specified.

INVALID_NUMBER_OF_TG_ROWS

Too many TG rows were specified.

NODE_ROW_WGT_LESS_THAN_LAST

The node rows were not listed in ascending order of weight.

TG_ROW_WGT_LESS_THAN_LAST

The TG rows were not listed in ascending order of weight.

State Check

If the command does not execute because of a state error, SNAplus2 returns the following parameters:

primary_rc

STATE_CHECK

secondary_rc

COS_TABLE_FULL

You cannot define a new COS because you would exceed the maximum number of COS definitions
allowed for the node (specified by the cos_cache_size parameter on the define_node command).

69

Administration Commands

define_cpic_side_info

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

2.13 define_cpic_side_info

The define_cpic_side_info command adds a side information entry to the configuration file or replaces
an existing entry. A CPI-C side information entry associates a set of conversation characteristics with a symbolic
destination name.

Because CPI-C side information entries are defined as domain resources, this command is not associated with a
particular node.

2.13.1 Supplied Parameters

Parameter name Type Length Default
[define_cpic_side_info]
sym_dest_name character 8
description character 31 (null string)
partner_lu_name character 17 (null string)
tp_name_type constant APPLICATION_TP
tp_name character 64 (null string)
mode_name character 8 (null string)
conversation_security_type constant NONE
security_user_id character 10 (null string)
security_password character 10 (null string)
lu_alias character 8 (null string)

Supplied parameters are:

sym_dest_name

Symbolic destination name that identifies the side information entry. The name can contain any displayable
character.

description

A text string describing the side information entry. SNAplus2 uses this string for information only. It is
stored in the node’s configuration file and returned on the query_cpic_side_info command.

partner_lu_name

Fully qualified name of the partner LU. Specify 3–17 type-A characters that consist of a 1–8 character network
name, followed by a period, followed by a 1–8 character partner LU name.

tp_name_type

The type of the target TP (the valid characters for a TP name are determined by the TP type). Possible values
are:

APPLICATION_TP

Application TP. All characters in the TP name must be valid ASCII characters.

SNA_SERVICE_TP

Service TP. The TP name must be specified as a hex array representing the 8 hexadecimal digits of
a 4-character name (for example 0x21F0F0F8). The first character (represented by two hexadecimal

70

digits) must be a hexadecimal value in the range 0x0–0x3F, excluding 0x0E and 0x0F; the remaining
characters (each represented by two hexadecimal digits) must be valid EBCDIC characters.

tp_name

TP name of the target TP.

mode_name

Name of the mode used to access the target TP.

conversation_security_type

Specifies whether the target TP uses conversation security. Allowed values:

NONE

The target TP does not use conversation security.

PROGRAM

The target TP uses conversation security. The security_user_id and security_password parameters are
used to access the target TP.

PROGRAM_STRONG

The target TP uses conversation security. The security_user_id and security_password parameters are
used to access the target TP. However, the local node must not send the password across the network
in clear text format. This option can be used only if the remote system supports password substitution.

Administration Commands

define_cpic_side_info

SAME

The target TP uses conversation security and can accept an “already verified” indicator from the local
TP. (This value indicates that the local TP was invoked by another TP, and has verified the security user
ID and password supplied by this TP.) The security_user_id parameter is used to access the target TP;
no password is required.

security_user_id

User ID used to access the partner TP. This parameter is not required if the conversation_security_type
parameter is set to NONE.

security_password

Password used to access the partner TP. This parameter is required only if the conversation_security_type
parameter is set to PROGRAM or PROGRAM_STRONG.

lu_alias

The alias of the local LU used to communicate with the target TP. This alias is a character string using any
locally displayable characters.

2.13.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

2.13.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

71

Administration Commands

define_default_pu

primary_rc

PARAMETER_CHECK

secondary_rc

INVALID_SYM_DEST_NAME

The sym_dest_name parameter contained a character that was not valid.

State Check

No specific state errors, other than those listed in Appendix A, Common Return Codes from snapadmin Commands,
occur for this command.

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

2.14 define_default_pu

The define_default_pu command defines the PU that is the default for handling SNAplus2 management
services data. Only one default PU for each node can be defined at any time; a second define_default_pu
for a different PU name overrides the previous definition.

The define_default_pu command enables the user to define, redefine, or modify any field of a default PU.
This command also enables the user to delete the default PU, by specifying a null PU name.

If an application issues the MS API verb TRANSFER_MS_DATA without specifying a PU name, the data is routed
to the default PU defined for the local node and sent on this PU’s session with the host SSCP. For more information
about TRANSFER_MS_DATA, refer to the HP-UX SNAplus2 MS Programmer’s Guide.

2.14.1 Supplied Parameters

Parameter name Type Length Default
[define_default_pu]
pu_name character 8
description character 31 (null string)

Supplied parameters are:

pu_name

Name of the PU that is to be the default PU; for this definition to have any effect, this must be a PU name
already defined as part of an LS definition. This name is a type-A character string starting with a letter.

To delete the default PU, specify all zeros.

description

A text string describing the PU. SNAplus2 uses this string for information only. It is stored in the node’s
configuration file and returned on the query_default_pu command.

2.14.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

72

Administration Commands

define_defaults

2.14.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

No parameter errors occur for this command.

State Check

No specific state errors, other than those listed in Appendix A, Common Return Codes from snapadmin Commands,
occur for this command.

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

2.15 define_defaults

The define_defaults command defines default parameters used by the node.

2.15.1 Supplied Parameters

Parameter name Type Length Default
[define_defaults]
description character 31 (null string)
mode_name character 8
implicit_plu_forbidden constant NO
specific_security_codes constant NO
limited_timeout decimal 0

Supplied parameters are:

description

A text string describing the default parameters. SNAplus2 uses this string for information only. It is stored
in the node’s configuration file and returned on the query_defaults command.

mode_name

Name of the default mode. If an application specifies an unrecognized mode name when attempting to start
a session, the parameters from this mode are used as a default definition for the unrecognized mode.

This mode must be either an SNA-defined mode or a mode defined by a previous define_mode command.
For more information about SNA-defined modes, refer to the HP-UX SNAplus2 Administration Guide. The
name is a type-A character string starting with a letter.

implicit_plu_forbidden

Specifies whether SNAplus2 puts implicit definitions in place for unknown partner LUs. Possible values are:

YES

SNAplus2 does not put implicit definitions in place for unknown partner LUs. All partner LUs must
be defined explicitly.

NO

73

Administration Commands

define_directory_entry

SNAplus2 puts implicit definitions in place for unknown partner LUs.

specific_security_codes

Specifies whether SNAplus2 uses specific sense codes on a security authentication or authorization failure.
Specific sense codes are only returned to those partner LUs which have reported support for them on the
session. Possible values are:

YES

SNAplus2 uses specific sense codes.

NO

SNAplus2 does not use specific sense codes.

limited_timeout

Specifies the timeout after which free limited-resource conwinner sessions are deactivated. Specify a value
in the range

0–65,535 seconds.

2.15.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

2.15.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

INVALID_MODE_NAME

The mode_name parameter did not match any defined mode name.

State Check

No specific state errors, other than those listed in Appendix A, Common Return Codes from snapadmin Commands,
occur for this command.

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists additional combinations of primary and
secondary return codes that are common to all commands.

2.16 define_directory_entry

The define_directory_entry command defines a new entry in the node directory database. It provides a
network qualified resource name along with a resource type (network node, end node, LU, or Wildcard). This
command cannot be used to modify existing entries.

74

Administration Commands

define_directory_entry

When defining an adjacent node and its LUs, use define_adjacent_len_node instead of de­fine_directory_entry. This enables you to define the node and its LUs with a single command. The
define_directory_entry command defines only a single entry, so you need to use multiple commands to

define entries for the adjacent node and for its LUs.

You can specify a “wildcard” LU name to match multiple LU names by specifying only the initial characters of the
name. For example, the wildcard LU name APPN.LU will match APPN.LUNAME or APPN.LU01 (but will not
match APPN.NAMELU).

2.16.1 Supplied Parameters

Parameter name Type Length Default
[define_directory_entry]
resource_name character 17
resource_type constant LU_RESOURCE
description character 31 (null string)
parent_name character 17 (null string)
parent_type constant ENCP_RESOURCE

Supplied parameters are:

resource_name

Fully qualified name of the resource to be registered. Specify 3–17 type-A characters that consist of a 1–8
character network name, followed by a period, followed by a 1–8 character resource name.

resource_type

Specifies the type of the resource to be defined. Possible values are:

ENCP_RESOURCE

End node (EN) or low-entry networking (LEN) node

NNCP_RESOURCE

Network node (NN)

LU_RESOURCE

Logical unit (LU)

WILDCARD_LU_RESOURCE

Wildcard LU name

The owning control point (CP) on the node must be defined before you can specify an LU or wildcard LU
resource type.

description

A text string describing the directory entry. SNAplus2 uses this string for information only. It is stored in the
node’s configuration file and returned on the query_directory_entry and query_directory_lu
commands.

parent_name

Fully qualified name of the parent resource; for an LU the parent resource is the owning control point and
for an end node or LEN node it is the network node server. Specify 3–17 type-A characters that consist of a
1–8 character network name, followed by a period, followed by a 1–8 character parent name.

Do not specify this parameter in the following cases:

• When registering a network node CP.

• When the command is being issued to an end node or LEN node to define an adjacent LEN node CP with

which the local node communicates directly.

75

Administration Commands

define_directory_entry

parent_type

Specifies the parent type of the resource to be defined. Possible values are:

ENCP_RESOURCE

End node (for an LU resource owned by an end node)

NNCP_RESOURCE

Network node (for an LU resource owned by a network node, or for an EN or LEN resource)

Do not specify this parameter when no parent name is supplied.

2.16.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

2.16.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

INVALID_FQ_OWNING_CP_NAME

The parent_name parameter did not match the name of a defined parent resource.

INVALID_LU_NAME

The resource_name parameter contained a character that was not valid or was not in the correct format.

INVALID_RESOURCE_TYPE

The resource_type parameter was not set to a valid value.

INVALID_WILDCARD_NAME

The resource_type parameter was set to
did not contain a valid wildcard entry.

DUPLICATE

The resource_name parameter contained a wildcard entry that has already been defined.

WILDCARD_LU_RESOURCE but the resource_name parameter

State Check

No specific state errors, other than those listed in Appendix A, Common Return Codes from snapadmin Commands,
occur for this command.

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

76

Administration Commands

define_dlur_defaults

2.17 define_dlur_defaults

The define_dlur_defaults command defines a default Dependent LU Server (DLUS) and a backup default
DLUS. If a default DLUS or backup default DLUS is already defined, the command overrides the existing definition.
DLUR uses the default DLUS name when it initiates SSCP-PU activation for PUs that do not have an explicitly
specified associated DLUS. (To define a PU and its associated DLUS, use define_internal_pu for a local
PU, or define_*_ls (for the appropriate link type) for a downstream PU.)

The command can also be used to revoke a default DLUS or backup default DLUS, so that one is not de

2.17.1 Supplied Parameters

Parameter name Type Length Default
[define_dlur_defaults]
description character 31 (null string)
dlus_name character 17
bkup_dlus_name character 17 (null string)
dlus_retry_timeout decimal 5
dlus_retry_limit decimal 3
prefer_active_dlus constant

fined.

Supplied parameters are:

description

A text string describing the DLUR defaults. SNAplus2 uses this string for information only. It is stored in
the node’s configuration file, but SNAplus2 does not make any other use of it.

dlus_name

Name of the DLUS node that is to be the default. Specify 3–17 type-A characters that consist of a 1–8
character network name, followed by a period, followed by a 1–8 character DLUS node name. To revoke the
current default DLUS, so that no default DLUS is defined, do not specify this parameter.

bkup_dlus_name

Name of the DLUS node that is to serve as the backup default. Specify 3–17 type-A characters that consist of
a1–8 character network name, followed by a period, followed by a 1–8 character backup DLUS node name.
To revoke the current backup default DLUS, so that no backup default DLUS is defined, do not specify this
parameter.

dlus_retry_timeout

The interval in seconds between the second and subsequent attempts to contact the DLUS specified by the
dlus_name and bkup_dlus_name parameters. The interval between the first and second attempts is always 1
second.

Specify a value in the range 1– 65,535.

dlus_retry_limit

Retry count for contacting a DLUS. This parameter is used to specify the number of times SNAplus2 should
retry if it fails to contact the DLUS on the first attempt.

Specify a value in the range 1–65,534, or specify 65,535 to indicate that SNAplus2 should retry indefinitely
until it contacts the DLUS.

prefer_active_dlus

Specifies how SNAplus2 operates when it receives a negative RSP(REQACTPU) from DLUS, or is attempting
to reactivate a failed DLUR PU. Possible values are:

YES

77

Administration Commands

define_dlur_defaults

If either the default primary DLUS or default backup DLUS is active, SNAplus2 will attempt to activate
or reactivate the PU by using the active DLUS only.

NO

SNAplus2 will attempt to activate or reactivate the PU by using the standard retry logic.

2.17.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

2.17.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

INVALID_DLUS_NAME

The supplied dlus_name parameter contained a character that was not valid or was not in the correct
format.

INVALID_BKUP_DLUS_NAME

The supplied bkup_dlus_name parameter contained a character that was not valid or was not in the
correct format.

State Check

No specific state errors, other than those listed in Appendix A, Common Return Codes from snapadmin Commands,
occur for this command.

Function Not Supported

If the command does not execute because the node’s configuration does not support it, SNAplus2 returns the
following parameters:

primary_rc

FUNCTION_NOT_SUPPORTED

The local node does not support DLUR; this support is defined by the dlur_support parameter on the
define_node command.

secondary_rc

(This parameter is not used.)

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

78

Administration Commands

define_downstream_lu

2.18 define_domain_config_file

The define_domain_config_file command specifies an optional comment string to be included in the
header of a domain configuration file. If you are creating a domain configuration file using a text editor, this
comment string must be the first record in the file.

2.18.1 Supplied Parameters

Parameter name Type Length Default
[define_domain_config_file]
comment character 100 (null string)

The supplied parameter is:

comment

An optional comment string containing information about the file. SNAplus2 uses the string for information
only. It is stored in the node’s configuration file and returned on the query_domain_config_file
command.

2.18.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

2.18.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

No parameter errors occur for this command.

State Check

No specific state errors, other than those listed in Appendix A, Common Return Codes from snapadmin Commands,
occur for this command.

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

2.19 define_downstream_lu

The define_downstream_lu command defines a new downstream LU and maps it to an upstream host LU
or LU pool. This enables the downstream LU to access the host computer using the PU concentration feature of
SNAplus2. This command cannot be used to modify an existing downstream LU.

This command can also be used to activate a downstream LU that is already defined (for example, because the
downstream workstation has just been activated). To do this, reissue the define_downstream_lu command
for that LU. Note that all parameters must be the same as in the original definition, because you cannot modify the
definition.

79

Administration Commands

define_downstream_lu

define_downstream_lu can also be used to define the downstream LU used by an application that
communicates with a SNAplus2 Primary RUI application. For more information about Primary RUI, see HP­UX SNAplus2 LUA Programmer’s Guide.

2.19.1 Supplied Parameters

Parameter name Type Length Default
[define_downstream_lu]
dslu_name character 8
description character 31 (null string)
nau_address decimal
dspu_name character 8
host_lu_name character 8
allow_timeout constant NO
delayed_logon constant NO

Supplied parameters are:

dslu_name

Name of the downstream LU to be defined. This name is a type-A character string starting with a letter.

description

A text string describing the downstream LU. SNAplus2 uses this string for information only. It is stored in
the node’s configuration file and returned on the query_downstream_lu command.

nau_address

Network accessible unit (NAU) address of the downstream LU. This must be in the range 1–255.

dspu_name

Name of the downstream PU associated with this LU, as specified on define_*_ls. This name is a type­A character string starting with a letter.

host_lu_name

Name of the host LU or host LU pool that the downstream LU uses. This name is an 8-byte type-A character
string.

For PU concentration, the host LU cannot be a dependent LU type 6.2. However, if the downstream LU is
LU type 6.2, you can configure the host LU as an LU type 0–3 and specify that the model type for the host
LU is unknown.

If the downstream LU is used to communicate with a SNAplus2 Primary RUI application instead of a host,
set this field to the string #PRIRUI#.

allow_timeout

Specifies whether to allow the session between the downstream LU and the upstream LU to timeout if the
session is left inactive for the timeout period specified on the upstream LU definition. Possible values are:

YES

Allow the session this downstream LU has with the upstream LU to timeout.

NO

Do not allow the session this downstream LU has with the upstream LU to timeout.

This field is ignored if the downstream LU is used to communicate with a SNAplus2 Primary RUI application
instead of a host.

delayed_logon

80

Administration Commands

define_downstream_lu

Specifies whether to use delayed logon with this downstream LU (the upstream LU is not activated until the
user requests it). Possible values are:

YES

Use delayed logon with this downstream LU; the upstream LU is not activated until the user requests
it.

NO

Do not use delayed logon with this downstream LU.

This field is ignored if the downstream LU is used to communicate with a SNAplus2 Primary RUI application
instead of a host.

2.19.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

2.19.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

INVALID_DNST_LU_NAME

The supplied dslu_name parameter contained a character that was not valid.

INVALID_NAU_ADDRESS

The supplied NAU address was not in the valid range.

INVALID_ALLOW_TIMEOUT

The supplied allow_timeout parameter value was not valid.

INVALID_DELAYED_LOGON

The supplied delayed_logon parameter value was not valid.

State Check

If the command does not execute because of a state error, SNAplus2 returns the following parameters:

primary_rc

STATE_CHECK

secondary_rc

Possible values are:

INVALID_PU_NAME

The specified dspu_name parameter value was not valid.

PU_NOT_DEFINED

81

Administration Commands

define_downstream_lu_range

The specified dspu_name parameter did not match any defined PU name.

INVALID_PU_TYPE

The PU specified by the dspu_name parameter is not a downstream PU that supports PU concentration.

LU_ALREADY_DEFINED

An LU with the name specified by the dslu_name parameter has already been defined, and cannot be
modified using this command.

DSLU_ACTIVE

The LU is already active.

LU_NAU_ADDR_ALREADY_DEFD

An LU with the NAU address specified by the nau_address parameter has already been defined.

INVALID_HOST_LU_NAME

The specified host_lu_name parameter value was not valid.

LU_NAME_POOL_NAME_CLASH

The specified LU name matches the name of an existing LU pool.

PU_NOT_ACTIVE

The PU specified by the dspu_name parameter is not currently active.

LU_ALREADY_ACTIVATING

An LU with the name specified by the dslu_name parameter is currently activating.

LU_DEACTIVATING

An LU with the name specified by the dslu_name parameter is currently deactivating.

LU_ALREADY_ACTIVE

An LU with the name specified by the dslu_name parameter is already active.

Function Not Supported

If the command does not execute because the node’s configuration does not support it, SNAplus2 returns the
following parameters:

primary_rc

FUNCTION_NOT_SUPPORTED

The local node does not support PU concentration; this support is defined by the pu_conc_support
parameter on the define_node command.

secondary_rc

(This parameter is not used.)

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

2.20 define_downstream_lu_range

The define_downstream_lu_range command defines a range of new downstream LUs and maps them to
an upstream host LU or LU pool. This command cannot be used to modify existing downstream LUs.

82

Administration Commands

define_downstream_lu_range

The supplied parameters include a base name for the new LUs and the range of NAU addresses. The LU base
name and NAU addresses are combined to generate the new LU names. For example, a base name of LUNME
combined with a NAU address in the range

11–14 results in the following LU names: LUNME011, LUNME012,

LUNME013 and LUNME014.

define_downstream_lu_range can also be used to define downstream LUs used by applications that
communicate with a SNAplus2 Primary RUI application. For more information about Primary RUI, see HP-UX
SNAplus2 LUA Programmer’s Guide.

2.20.1 Supplied Parameters

Parameter name Type Length Default
[define_downstream_lu_range]
dslu_base_name character 5
description character 31 (null string)
min_nau decimal 1
max_nau decimal 1
dspu_name character 8
host_lu_name character 8
allow_timeout constant NO
delayed_logon constant NO

Supplied parameters are:

dslu_base_name

Base name for the names of the new LUs. This name is a type-A character string of 1–5 characters starting
with a letter. SNAplus2 generates an LU name for each LU by appending the 3-digit decimal value of the
NAU address to the base name.

description

A text string describing the downstream LUs; the same string is used for each LU in the range. SNAplus2
uses this string for information only. It is stored in the node’s configuration file and returned on the
query_downstream_lu command.

min_nau

NAU address of the first LU, in the range 1–255.

max_nau

NAU address of the last LU, in the range 1–255.

dspu_name

Name of the downstream PU (as specified on define_*_ls, where
downstream LUs in this range use. The name is a type-A character string starting with a letter.

host_lu_name

Name of the host LU or host LU pool to which the downstream LUs in the given range are mapped. The
name is an 8-byte type-A character string.

If the downstream LUs are used to communicate with a SNAplus2 Primary RUI application instead of a host,
set this field to the string #PRIRUI#.

allow_timeout

Specifies whether to allow the sessions this range of downstream LUs have with the upstream LU to timeout
if the session is left inactive for the timeout period specified on the upstream LU definition. Possible values
are:

* is replaced by the LS type) that the

YES

Allow the sessions this range of downstream LUs have with the upstream LU to timeout.

83

Administration Commands

define_downstream_lu_range

NO

Do not allow the session this range of downstream LUs have with the upstream LU to timeout.

This field is ignored if the downstream LUs are used to communicate with a SNAplus2 Primary RUI application
instead of a host.

delayed_logon

Specifies whether to use delayed logon with this range of downstream LUs (the upstream LU is not activated
until the user requests it). Possible values are:

YES

Use delayed logon with this range of downstream LUs; the upstream LU is not activated until the user
requests it.

NO

Do not use delayed logon with this range of downstream LUs.

This field is ignored if the downstream LUs are used to communicate with a SNAplus2 Primary RUI application
instead of a host.

2.20.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

2.20.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

INVALID_DNST_LU_NAME

The supplied dslu_base_name parameter contained a character that was not valid.

INVALID_NAU_ADDRESS

The min_nau parameter value, max_nau parameter value, or both parameter values were not in the valid
range.

INVALID_ALLOW_TIMEOUT

The supplied allow_timeout parameter value was not valid.

INVALID_DELAYED_LOGON

The supplied delayed_logon parameter value was not valid.

State Check

If the command does not execute because of a state error, SNAplus2 returns the following parameters:

primary_rc

84

STATE_CHECK

secondary_rc

Possible values are:

INVALID_PU_NAME

The specified dspu_name parameter value was not valid.

PU_NOT_DEFINED

The specified dspu_name parameter did not match any defined PU name.

INVALID_PU_TYPE

The PU specified by the dspu_name parameter is not a downstream PU that supports PU concentration.

LU_ALREADY_DEFINED

An LU has already been defined with a name that matches one of the names in the range. The existing
LU cannot be modified using this command.

DSLU_ACTIVE

An LU with a name that matches one of the names in the range is already active. The existing LU
cannot be modified using this command.

LU_NAU_ADDR_ALREADY_DEFD

Administration Commands

define_dspu_template

An LU has already been defined with an NAU address that matches one of the addresses in the range.

INVALID_HOST_LU_NAME

The specified host_lu_name parameter value was not valid.

LU_NAME_POOL_NAME_CLASH

One of the LU names in the range matches the name of an existing LU pool.

Function Not Supported

If the command does not execute because the node’s configuration does not support it, SNAplus2 returns the
following parameters:

primary_rc

FUNCTION_NOT_SUPPORTED

The local node does not support PU concentration; this support is defined by the pu_conc_support
parameter on the

define_node command.

secondary_rc

(This parameter is not used.)

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

2.21 define_dspu_template

The define_dspu_template command defines a template for the downstream LUs that use the SNAplus2 PU
concentration feature. This template is used to define downstream LUs on a group of downstream workstations
when a workstation connects over an implicit link (a link not previously defined)..

85

Administration Commands

define_dspu_template

define_dspu_template can also be used to define downstream LUs that support applications communicating
with a Primary RUI application on the SNAplus2 node. For more information about Primary RUI, see HP-UX
SNAplus2 LUA Programmer’s Guide.

2.21.1 Supplied Parameters

Parameter name Type Length Default
[define_dspu_template]
template_name character 8
description character 32 (null string)
modify_template constant REPLACE_DSPU_TEMPLATE
max_instance decimal 0

{dslu_template}
min_nau decimal
max_nau decimal
host_lu character 8
allow_timeout constant NO
delayed_logon constant NO

Supplied parameters are:

template_name

The name of the template for downstream LUs that are present on a group of downstream workstations.

description

Resource description that is returned on the query_dspu_template command.

modify_template

Specifies whether this command should add additional DSLU templates to an existing DSPU template or
should replace an existing DSPU template. Possible values are:

MODIFY_DSPU_TEMPLATE

If the named DSPU template does not exist, then it is created. If the named DSPU template does exist,
then the DSLU templates supplied to this command are added to the existing DSPU template.

REPLACE_DSPU_TEMPLATE

A new template is created, overwriting any existing definition.

max_instance

The maximum number of instances of the template that can be active concurrently. When the limit is reached,
no new instances are created. Specify a value in the range 0–65,535, where 0 indicates no limit.

The subrecord

dslu_template contains the following parameters:

min_nau

NAU address of the first downstream PU, in the range 1–255.

max_nau

NAU address of the last downstream PU, in the range 1–255.

host_lu

Name of the host LU or host LU pool that the downstream LU uses. This name is an 8-byte type-A character
string.

If the downstream LUs are used to communicate with a SNAplus2 Primary RUI application instead of a host,
set this field to the string #PRIRUI#.

86

Administration Commands

define_dspu_template

allow_timeout

Specifies whether to timeout host LUs used by the downstream LU if the session is left inactive for the
timeout period specified on the host LU definition. Possible values are:

YES

SNAplus2 is allowed to timeout host LUs used by this downstream LU.

NO

SNAplus2 is not allowed to timeout host LUs used by this downstream LU.

This field is ignored if the downstream LUs are used to communicate with a SNAplus2 Primary RUI application
instead of a host.

delayed_logon

Specifies whether to delay connecting the downstream LU to the host LU until the first data is received from
the downstream LU. Possible values are:

YES

SNAplus2 delays connecting the downstream LU to the host LU. A simulated logon screen is sent to
the downstream LU.

NO

SNAplus2 does not delay connecting the downstream LU to the host LU.

This field is ignored if the downstream LUs are used to communicate with a SNAplus2 Primary RUI application
instead of a host.

2.21.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

2.21.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

INVALID_TEMPLATE_NAME

The name specified for the template_name parameter was not valid.

INVALID_NAU_RANGE

The address specified on the min_nau or max_nau parameters was not in the valid range.

CLASHING_NAU_RANGE

The range of addresses specified by the min_nau parameter through the max_nau parameter in a

dslu_template subrecord clashes with a range specified by another dslu_template subrecord in the template

named by the template_name parameter.

87

Administration Commands

define_emulator_user

State Check

If the command does not execute because of a state error, SNAplus2 returns the following parameters:

primary_rc

STATE_CHECK

secondary_rc

Possible values are:

INVALID_HOST_LU_NAME

The specified host_lu_name parameter value was not valid.

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

2.22 define_emulator_user

The define_emulator_user command identifies a user of the SNAplus2 system who can use 3270 emulation
or 5250 emulation, and it defines the resources available to that user. Use this command to define a new user, to
define new sessions for use by an existing user, or to modify the user parameters and session parameters for an
existing user. (To delete sessions from an existing user, use delete_emulator_user.)

This command is not associated with a particular node because emulation program users are defined as domain
resources.

2.22.1 Supplied Parameters

Parameter name Type Length Default
[define_emulator_user]
user_name character 32
description character 31 (null string)
style_file character 8 (null string)
max_act_sessions decimal 10
view_rtm constant NO
alert_permission constant NO
change_lu constant NO
change_style constant NORMAL
user_is_group constant NO

{3270_session_data}
session_name character 8
description character 31 (null string)
lu_name character 8
session_type constant 3270_DISPLAY_MODEL_2
model_override constant YES

(One or more 3270_session_data subrecords may be included.)

{5250_session_data}
session_name character 8
description character 31 (null string)
local_lu_alias character 8

88

Administration Commands

plu_alias character 8 (null string)
fqplu_name character 17 (null string)
mode_name character 8 QPCSUPP
session_type constant 5250_DISPLAY

define_emulator_user

(One or more

5250_session_data

subrecords may be included.)

Supplied parameters are:

user_name

The name of the emulation program user. This name is character string of 1–32 locally displayable characters.
Possible values are:

• The HP-UX user ID of a 3270 or 5250 user on the SNAplus2 computer (or, for a Win16 Client user, the
user name specified in the SNAplus2 client network data file). The

user_is_group parameter must be set

to NO.

• The HP-UX group ID of a group of 3270 or 5250 user on the SNAplus2 computer (or, for a Windows
Client user, the group name specified in the SNAplus2 client network data file). The user_is_group
parameter must be set to YES.

To set up a default record that will be used by any user not explicitly named in the con

figuration, specify the

record name <DEFAULT> (in uppercase and including the angle bracket characters), and set user_is_group to
NO. To restrict use of the emulation program to users and groups that are explicitly named in the configuration,
do not specify <DEFAULT>.

When the user starts the emulation program, SNAplus2 checks the user ID against the emulator user records
in the configuration to find the correct record, in this order:

• If the user ID matches a record for a specific user name, the specific user name record is used.

• If the user ID cannot be matched but the user’s group ID matches a record for a group, the group ID

record is used.

• If the user ID and the group ID cannot be matched but there is a <DEFAULT> record defined, the default
record is used.

description

An optional string of 0–31 characters. SNAplus2 uses this string for information only. It is stored in the
node’s configuration file and returned on the query_emulator_user_def command. You can use it to
store additional information such as the user’s full name, to help distinguish between users.

style_file

The name of this user’s default style file. This name is a string of 1–8 characters. For HP-UX systems, the
actual file name used is the name specified here with the extension .stu (3270) or .stx (5250) appended to
it. For Windows systems, refer to the emulator documentation for details about style file naming conventions.

max_act_sessions

The maximum number of sessions that this user can access simultaneously. (For a 5250-only user, this
parameter is ignored.) Use this parameter as follows:

• To prevent the user from using 3270 emulation, set this parameter to 0 (zero).

• To restrict the number of sessions that the user can use simultaneously, set this parameter to a value
between 1 and 10 (or between 1 and the total number of sessions defined for the user if it is less than 10).

• To specify no limit, set this parameter to any value above 10.

view_rtm

Specifies whether the user has permission to view response time monitor (RTM) data. This parameter also
determines whether the Last Transaction Time Indicator (LTTI) is displayed on the 3270 status line. (For a
5250-only user, this parameter is ignored.) Possible values are:

89

Administration Commands

define_emulator_user

YES

The user has permission to view RTM data. The LTTI is displayed.

NO

The user does not have permission to view RTM data. The LTTI is not displayed.

alert_permission

Specifies whether the user has permission to send 3270 user alerts. (For a 5250-only user, this parameter is
ignored.) Possible values are:

YES

The user can send 3270 user alerts.

NO

The user cannot send 3270 user alerts.

change_lu

Specifies whether the user has permission to change the mapping of 3270 sessions to LUs (either by remapping
them from within the 3270 user interface or by specifying LU names on the command line when starting the
3270 emulation program). (For a 5250-only user, this parameter is ignored.) Possible values are:

YES

The user can change the mapping of 3270 sessions to LUs.

NO

The user cannot change the mapping of 3270 session to LUs.

change_style

Specifies whether the user has permission to load or modify 3270 style files. Possible values are:

ADVANCED

The user can specify a style file name when starting the 3270 emulation program and can create or
modify style files using the 3270 emulation program’s menu interface.

NORMAL

The user can specify a style file name when starting the 3270 emulation program and can create or
modify style files using the 3270 emulation program’s menu interface. The user cannot modify the
default style file specified by the

style_file parameter.

The 3270 emulation program does not distinguish between the two values ADVANCED and NORMAL;to
prevent users from modifying the default style file, you should set the permissions on this file so that users
do not have write access to it.

INITIAL

The user can specify a style file name on the command line when starting the 3270 emulation program,
but cannot load, create, or modify style files from within the menu interface. This option enables you
to provide a choice of standard initial style files for a user.

RESTRICTED

The user is restricted to the default style file specified by the style_file parameter and cannot create or
modify style files.

user_is_group

Specifies whether the user_name parameter identifies a group name or a user name. Possible values are:

90

Administration Commands

define_emulator_user

YES

The user_name parameter identifies a group name. Any user in this group will use this emulator user
record unless there is an explicit record for the user’s user name.

NO

The user_name parameter identifies a user name.

One or more

3270_session_data subrecords may follow. Each subrecord contains the following additional parameters:

session_name

A name identifying the session. This name is an 8-byte string consisting of locally displayable characters.
If the name matches an existing session name defined for this 3270 user, the information for that session is
replaced; otherwise, a new session is added.

To define sessions that are initially displayed in the 3270 emulation program’s control interface, specify a
name in the range

SESS0001–SESS0010. These names correspond to the session numbers 1–10 in the
control interface. If you use the names SESS0002, SESS0003, and SESS0005, the control interface will
display session numbers 2, 3, and 5 using the information defined for these names. (The names SESS0001–
SESS0010 are not displayed in the control interface; they are replaced by the long names defined for these
sessions in the 3270 style file.)

Sessions that are available for the user to remap to must be given names that are not in the range SESS0001–
SESS0010. The user will be able to access these sessions only if the change_lu parameter enables the user
to remap sessions.

description

An optional string of 0–31 characters. SNAplus2 uses this string for information only. It is stored in the
node’s configuration file and returned on the query_emulator_user_def command.

lu_name

Name of the LU or LU pool that this session uses. This name is an 8-byte type-A character string. It must
match the name of a type 0–3 LU or an LU pool that has already been defined.

If you assign the session to an LU that is in an LU pool, SNAplus2 will try to use this LU when the session
is activated. If the LU is not available, SNAplus2 will attempt to find a free LU from the pool (as though the
session had been assigned to the pool).

session_type

Type of the LU or pool (display or printer, and the screen model for display LUs). Possible values are:

3270_DISPLAY_MODEL_2

Display model 2 (80 x 24)

3270_DISPLAY_MODEL_3

Display model 3 (80 x 32)

3270_DISPLAY_MODEL_4

Display model 4 (80 x 43)

3270_DISPLAY_MODEL_5

Display model 5 (132 x 27)

PRINTER

Printer LU (this value is not valid if lu_name specifies an LU pool)

model_override

91

Administration Commands

define_emulator_user

Specifies whether the user has permission to change the session to use a different screen model from the one
specified. Possible values are:

YES

The user can change the screen model.

NO

The user cannot change the screen model.

One or more

session_name

description

local_lu_alias

plu_alias

fqplu_name

5250_session_data subrecords may follow. Each subrecord contains the following additional parameters:

A name identifying the session. This name is an 8-byte string consisting of locally displayable characters.
If the name matches an existing session name defined for this 5250 user, the information for that session is
replaced; otherwise, a new session is added.

An optional string of 0–31 characters. SNAplus2 uses this string for information only. It is stored in the
node’s configuration file and returned on the

LU alias of the local LU that this session uses. This must match the name of an APPC local LU that has
already been defined.

LU alias of the partner LU that this session uses.

To indicate that the partner LU is identified by its fully qualified name instead of its LU alias, do not specify
this parameter, and specify the fully qualified name in the
Section 2.43, define_partner_lu.

Fully qualified name of the partner LU. Specify 3–17 type-A characters that consist of a 1–8 character net­work name, followed by a period, followed by a 1–8 character partner LU name.

query_emulator_user_def command.

fqplu_name parameter. For more information, see

This parameter is used only if the plu_alias parameter is not specified; it is ignored if plu_alias is specified.

mode_name

Name of the mode that this session uses. This name is an 8-byte type-A character string starting with a letter.
The mode name must match the name of an APPC mode that has already been defined; it is generally set to
the SNA-defined mode name QPCSUPP.

session_type

Type of the 5250 session (display or printer). Possible values are:

5250_DISPLAY

Display session

5250_PRINTER

Printer session

2.22.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

92

Administration Commands

define_fddi_ls

2.22.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

No parameter errors occur for this command.

State Check

No specific state errors, other than those listed in Appendix A, Common Return Codes from snapadmin Commands,
occur for this command.

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

2.23 define_ethernet_dlc

For more information, see Section 2.59, define_tr_dlc, define_ethernet_dlc, define_fddi_dlc.

2.24 define_ethernet_ls

For more information, see Section 2.60, define_tr_ls, define_ethernet_ls, define_fddi_ls.

2.25 define_ethernet_port

For more information, see Section 2.61, define_tr_port, define_ethernet_port, define_fddi_port.

2.26 define_fddi_dlc

For more information, see Section 2.59, define_tr_dlc, define_ethernet_dlc, define_fddi_dlc.

2.27 define_fddi_ls

For more information, see Section 2.60, define_tr_ls, define_ethernet_ls, define_fddi_ls.

93

Administration Commands

define_focal_point

2.28 define_fddi_port

For more information, see Section 2.61, define_tr_port, define_ethernet_port, define_fddi_port.

2.29 define_focal_point

The define_focal_point command defines a focal point for a particular Management Services category. When
a new focal point is defined, SNAplus2 attempts to establish an implicit primary focal point relationship with the
defined focal point by sending an MS_CAPABILITIES request.

2.29.1 Supplied Parameters

Parameter name Type Length Default
[define_focal_point]
ms_category character 8
fp_fqcp_name character 17 (null string)
ms_appl_name character 8 (null string)
description character 31 (null string)
backup constant NO

Supplied parameters are:

ms_category

Management Services category. This category is one of the following:

• One of the category names specified in SNA Management Services Reference. Specify the name as a

hexadecimal array (for example 0x23F0F3F1).

• A user-defined category name. Specify the name as a type-1134 character string.

fp_fqcp_name

Fully qualified control point name of the focal point to be defined. Specify 3–17 type-A characters that consist
of a 1–8 character network name, followed by a period, followed by a 1–8 character CP name.

To revoke the existing focal point for the specified MS category, do not specify this parameter.

ms_appl_name

Management Services focal point application name. This name is usually a type-1134 character string;
alternatively, it can be one of the MS Discipline-Specific Application Program names specified in SNA
Management Services Reference.

description

A text string describing the focal point. SNAplus2 uses this string for information only. It is stored in the
node’s configuration file and returned on the query_focal_point command.

backup

Indicates whether the specified application is the backup focal point or the main focal point for this category.
Possible values are:

94

YES

The application is the backup focal point (used only if the main focal point is not available).

NO

Administration Commands

define_focal_point

The application is the main focal point.

2.29.2 Returned Parameters

If the command executes successfully, SNAplus2 returns the following parameter:

primary_rc

OK

The focal point was defined as requested.

2.29.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

INVALID_CATEGORY_NAME

ms_category parameter contained a character that was not valid.

The

INVALID_FP_NAME

The fp_fqcp_name or ms_appl_name parameter value was not valid.

State Check

No specific state errors, other than those listed in Appendix A, Common Return Codes from snapadmin Commands,
occur for this command.

Function Not Supported

If the command does not execute because the node’s configuration does not support it, SNAplus2 returns the
following parameters:

primary_rc

FUNCTION_NOT_SUPPORTED

The local node does not support MS network management functions; support is defined by the
mds_supported parameter on the define_node command.

secondary_rc

NO_SECONDARY_RC

Other Conditions

If the command does not execute because other conditions exist, SNAplus2 returns the following parameters:

primary_rc

REPLACED

Another define_focal_point command was issued to the same node while this command was
outstanding, specifying a different focal point for the same MS category. This command was ignored;
the node will attempt to contact the focal point specified by the second command.

95

Administration Commands

define_internal_pu

secondary_rc

NO_SECONDARY_RC

primary_rc

UNSUCCESSFUL

secondary_rc

Possible values are:

IMPLICIT_REQUEST_REJECTED

The specified focal point rejected the request.

IMPLICIT_REQUEST_FAILED

The node could not send the request to the specified focal point; this may be because the specified
control point or application was not found.

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

2.30 define_internal_pu

The define_internal_pu command defines a PU on the local node that is served by DLUR. (To define a
downstream PU served by DLUR or PU concentration, or to define a local PU that is directly attached to the host,
use define_*_ls (for the appropriate link type) instead of define_internal_pu.)

2.30.1 Supplied Parameters

Parameter name Type Length Default
[define_internal_pu]
pu_name character 8
description character 31 (null string)
dlus_name character 17 (null string)
bkup_dlus_name character 17 (null string)
pu_id hex array 4
initially_active constant NO
dlus_retry_timeout decimal (0)
dlus_retry_limit decimal (0)
dddlu_offline_supported constant NO

Supplied parameters are:

pu_name

Name of the internal PU to be defined. This name is a type-A character string starting with a letter.

This name should match the PU name configured on the host. (SNAplus2 sends both the PU name and PU
ID to the host to identify the PU. The host normally identifies the PU by its PU name, or by the PU ID if it
cannot find a matching PU name.)

description

A text string describing the internal PU. SNAplus2 uses this string for information only. It is stored in the
node’s configuration file and returned on the query_dlur_pu and query_pu commands.

dlus_name

96

Administration Commands

define_internal_pu

Name of the DLUS node that DLUR will use when it initiates SSCP-PU activation. Specify 3–17 type-A
characters that consist of a 1–8 character network name, followed by a period, followed by a 1–8 character
DLUS node name.

To indicate that DLUR should use the global default DLUS, do not specify this parameter. In this case, you
must also use

define_dlur_defaults to define a global default DLUS.

bkup_dlus_name

Name of the DLUS node that will serve as the backup DLUS for this PU. Specify 3–17 type-A characters that
consist of a 1–8 character network name, followed by a period, followed by a 1–8 character backup DLUS
name.

To indicate that DLUR should use the global backup default DLUS, do not specify this parameter. In this
case, you must also use define_dlur_defaults to define a global backup default DLUS.

pu_id

PU identifier. This ID is a 4-byte hexadecimal string, consisting of a block number (three hexadecimal digits)
and a node number (five hexadecimal digits). The PU ID must match the

pu_id configured at the host.

initially_active

Specifies whether this internal PU is automatically started when the node is started. Possible values are:

YES

The PU is automatically started when the node is started.

NO

The PU is not automatically started; it must be manually started.

dlus_retry_timeout

The interval in seconds between the second and subsequent attempts to contact the DLUS specified by the
dlus_name and bkup_dlus_name parameters. The interval between the first and second attempts is always 1
second.

Specify a value in the range 0– 65,535.If0 (zero) is specified, then the defaults specified using the de-
fine_dlur_defaults command are used.

dlus_retry_limit

Retry count for contacting a DLUS. This parameter is used to specify the number of times SNAplus2 should
retry if it fails to contact the DLUS on the first attempt.

Specify a value in the range 1–65,534, or specify 65,535 to indicate that SNAplus2 should retry indefinitely
until it contacts the DLUS.

dddlu_offline_supported

Specifies whether the local PU should send NMVT (power off) messages to the host. If the host system
supports DDDLU (Dynamic Definition of Dependent LUs), SNAplus2 sends NMVT (power off) to the host
when it has finished using a dynamically defined LU. This allows the host to save resources by removing the
definition when it is no longer required.

Possible values are:

YES

The local PU sends NMVT (power off) messages to the host.

NO

The local PU does not send NMVT (power off) messages to the host.

If the host supports DDDLU but does not support the NMVT (power off) message, this parameter must be
set to NO.

97

Administration Commands

define_internal_pu

2.30.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

2.30.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

INVALID_PU_NAME

The pu_name parameter contained a character that was not valid.

INVALID_PU_ID

The pu_id parameter contained a character that was not valid.

INVALID_DLUS_NAME

The dlus_name parameter contained a character that was not valid or was not in the correct format.

INVALID_BKUP_DLUS_NAME

The bkup_dlus_name parameter contained a character that was not valid or was not in the correct for­mat.

State Check

If the command does not execute because of a state error, SNAplus2 returns the following parameters:

primary_rc

STATE_CHECK

secondary_rc

PU_ALREADY_DEFINED

A PU with the specified name has already been defined.

Function Not Supported

If the command does not execute because the node’s configuration does not support it, SNAplus2 returns the
following parameters:

primary_rc

FUNCTION_NOT_SUPPORTED

The local node does not support DLUR; this support is defined by the dlur_support parameter on the
define_node command.

secondary_rc

(This parameter is not used.)

Other Conditions

Appendix A, Common Return Codes from snapadmin Commands, lists combinations of primary and secondary
return codes that are common to all commands.

98

Administration Commands

define_ip_dlc

2.31 define_ip_dlc

The define_ip_dlc command defines a new DLC for use with Enterprise Extender (HPR/IP). The command
can also be used to modify an existing DLC, if the DLC is not currently active.

2.31.1 Supplied Parameters

Parameter name Type Length Default
[define_ip_dlc]
dlc_name character 8
description character 31 (null string)
initially_active constant YES
udp_port_llc decimal 12000
udp_port_network decimal 12001
udp_port_high decimal 12002
udp_port_medium decimal 12003
udp_port_low decimal 12004
ip_precedence_llc decimal 6
ip_precedence_network decimal 6
ip_precedence_high decimal 4
ip_precedence_medium decimal 2
ip_precedence_low decimal 1
no_dns_lookup constant NO

Supplied parameters are:

dlc_name

Name of the DLC. This name is a character string using any locally displayable characters.

description

A text string describing the DLC. SNAplus2 uses this string for information only. It is stored in the node’s
configuration file and returned on the query_dlc command.

initially_active

Specifies whether this DLC is automatically started when the node is started. Possible values are:

YES

The DLC is automatically started when the node is started.

NO

The DLC is automatically started only if a port or LS that uses the DLC is defined as initially active;
otherwise, it must be manually started.

udp_port_llc

UDP port number used for LLC commands.

udp_port_network

UDP port number used for network priority traffic.

udp_port_high

UDP port number used for high priority traffic.

udp_port_medium

UDP port number used for medium priority traffic.

99

Administration Commands

define_ip_dlc

udp_port_low

UDP port number used for low priority traffic.

ip_precedence_llc

IP precedence value used for LLC commands, in the range 0 (minimum)—7 (maximum).

ip_precedence_network

IP precedence value used for network priority traffic, in the range 0 (minimum)—7 (maximum).

ip_precedence_high

IP precedence value used for high priority traffic, in the range 0 (minimum)—7 (maximum).

ip_precedence_medium

IP precedence value used for medium priority traffic, in the range 0 (minimum)—7 (maximum).

ip_precedence_low

IP precedence value used for low priority traffic, in the range 0 (minimum)—7 (maximum).

no_dns_lookup

Specifies whether remote host IP addresses are specified as IPv4 dotted-decimal addresses or as names
requiring lookup at a Domain Name Server. Possible values are:

YES

The remote host IP address on each link station defined for this DLC is specified as a dotted-decimal
IP address (such as 193.1.11.100). The DLC does not need to perform any Domain Name Server
lookup for incoming or outgoing calls.

NO

The remote host IP address on link stations defined for this DLC can be specified as a dotted-decimal
IP address (such as 193.1.11.100), as a name (such as newbox.this.co.uk), or as an alias
(such as newbox). The node performs a Domain Name Server lookup to determine the remote host
name on all incoming calls, and on outgoing calls for link stations where the remote host IP address is
specified as a name or alias.

2.31.2 Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

2.31.3 Error Return Codes

If the command cannot be executed, SNAplus2 returns a primary return code to indicate the type of error and a
secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

INVALID_DLC_NAME

100

The supplied dlc_name parameter contained a character that was not valid.