Batch

PSS/E-29
GUIDE TO PSS/E BATCH COMMANDS
October 2002
Copyright 1990-2002 Power Technologies, Inc.

Information in this manual and any software described herein is confidential and subject to change
without notice and does not represent a commitment on the part of Power Technologies, Inc. The
software described in this manual is furnished under a license agreement or nondisclosure agreement
and may be used or copied only in accordance with the terms of the agreement. No part of this
manual may be reproduced or transmitted in any form or by any means, electronic or mechanical,
including photocopying, for any purpose other than the purchasers personal use, without the express
written permission of Power Technologies, Inc.
Microsoft Windows 98, Windows 2000, Windows NT, Windows XP, and Visual C++ are registered
trademarks of Microsoft Corporation.
TABLE OF CONTENTS
CHAPTER 1 - POWER FLOW APIS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-1

1.1
1.2
1.3
1.4
1.5
1.6
1.7
1.8
1.9
1.10
1.11
1.12
1.13
1.14
1.15
1.16
1.17
1.18
1.19
1.20
1.21
1.22
1.23
1.24
1.25
1.26
1.27
1.28
1.29
1.30
1.31
1.32
1.33
1.34
1.35
1.36
PSS/E-29
Default Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-1

ACCCAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2
ALPHNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-4
ANSIAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-5
AREA_INTERCHANGE_CONTROL_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-7
AREANW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-8
ARNMNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-9
ASCCNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-10
BASE_FREQUENCY_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-12
BGENNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-13
BKDYNW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-14
BMATAPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-15
BRCHNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-16
BSNMNW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-18
BUS_INPUT_API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-21
BUS_OUTPUT_API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-22
BUSNAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-23
CASENW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-24
CMPRNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-25
CNTBNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-27
CONNECTIVITY_CHECK_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-31
CONGAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-32
CONLNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-33
DC_TAP_ADJUSTMENT_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-35
DCCCAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-36
DCLFNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-38
DFAXAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-40
DFTIAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-41
DIFFNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-43
DSCNAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-46
DYN_UNBAL_FAULT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-47
ECDINW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-49
ECHOAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-50
EEQVNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-51
EQRDNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-52
EXAMNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-53
TABLE OF CONTENTS
1.37
1.38
1.39
1.40
1.41
1.42
1.43
1.44
1.45
1.46
1.47
1.48
1.49
1.50
1.51
1.52
1.53
1.54
1.55
1.56
1.57
1.58
1.59
1.60
1.61
1.62
1.63
1.64
1.65
1.66
1.67
1.68
1.69
1.70
1.71
1.72
1.73
1.74
1.75
1.76
1.77
1.78
1.79
1.80
1.81
ii
Power Technologies, Inc.
EXTRNW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-54
FACTAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-55
FDNSAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-56
FILE_OVERWRITE_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-58
FINDAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-59
FLATAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-60
FNSLAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-61
GCAPNW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-63
GDIFAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-64
GENSNW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-65
GEOLNW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-66
GNETNW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-67
GSDFLT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-68
IMPCAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-69
INLFAPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-70
INTANW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-72
INTZNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-73
JOINAPI/JOINNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-74
LAMPNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-76
LINE_SHUNT_REPORTING_API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-77
LINES_PER_PAGE_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-78
LISTNW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-79
LLRFAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-80
LOUTNW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-82
LTAPAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-83
MATRIX_GROWTH_FACTOR_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-84
MBID2DC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-85
MBID3WND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-86
MBIDATRN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-87
MBIDBRN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-88
MBIDFACTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-89
MBIDLOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-90
MBIDMAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-91
MBIDMDC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-92
MBIDMSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-93
MBIDVSC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-94
MCREAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-95
MODRNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-96
MOVE3WND. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-97
MOVEBRN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-98
MOVELOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-99
MOVELOADS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-100
MOVEMAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-101
MOVEPLNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-102
MOVESWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-103
PSS/E-29
TABLE OF CONTENTS
1.82 MSLVAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-104

1.83 MTDCAPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-106
1.84 MULTISECTION_LINE_REPORTING_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-107
1.85 NETGNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-108
1.86 NEWCASNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-109
1.87 NEWTON_TOLERANCE_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-110
1.88 NON_DIVERGENT_API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-111
1.89 NRDFLT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-112
1.90 NSOLAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-114
1.91 ORDRAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-116
1.92 OTDFAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-117
1.93 OUTSNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-118
1.94 OWNMAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-119
1.95 OWNRNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-120
1.96 PP_ACCC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-121
1.97 PATHAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-123
1.98 PHASE_SHIFT_ADJUSTMENT_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-124
1.99 POLYAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-125
1.100 POUTNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-128
1.101 POWER_OUTPUT_API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-129
1.102 PRTIAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-130
1.103 PURG2DC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-131
1.104 PURG3WND. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-132
1.105 PURGATRN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-133
1.106 PURGBRN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-134
1.107 PURGFACTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-135
1.108 PURGLOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-136
1.109 PURGLOADS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-137
1.110 PURGMAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-138
1.111 PURGMDC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-139
1.112 PURGMSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-140
1.113 PURGMUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-141
1.114 PURGNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-142
1.115 PURGPLNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-143
1.116 PURGSWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-144
1.117 PURGVSC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-145
1.118 RANKNW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-146
1.119 RATENW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-148
1.120 RATING_SET_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-149
1.121 RAWDAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-150
1.122 RAWDNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-152
1.123 RDCHAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-153
1.124 RDEQNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-154
1.125 READAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-155
1.126 READSUB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-156
PSS/E-29
iii
TABLE OF CONTENTS
1.127 RECNAPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-158

1.128 REGBNW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-159
1.129 REMMAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-160
1.130 RESQAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-161
1.131 RETIAPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-162
1.132 RNFIAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-163
1.133 RWCMAPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-164
1.134 RWMANW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-165
1.135 RWMMAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-166
1.136 RWSQNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-167
1.137 SAVE_OPTION_SETTINGS_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-168
1.138 SAVENW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-169
1.139 SCALNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-170
1.140 SCEQNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-173
1.141 SCGRAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-174
1.142 SCMUAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-176
1.143 SCOPAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-181
1.144 SEQDAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-182
1.145 SEQUENCE_NETWORK_SETUP_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-183
1.146 SHNTNW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-184
1.147 SHORT_CIRCUIT_COORDINATES_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-185
1.148 SHORT_CIRCUIT_MODELING_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-186
1.149 SHORT_CIRCUIT_UNITS_API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-187
1.150 SHORT_CIRCUIT_WARNING_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-188
1.151 SHOWAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-189
1.152 SIZE_LEVEL_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-190
1.153 SIZEAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-191
1.154 SOLVAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-192
1.155 SPCBAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-194
1.156 SPILAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-196
1.157 SPLTAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-199
1.158 SQEXNW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-200
1.159 SQLINW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-201
1.160 STOPAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-202
1.161 SUBSNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-203
1.162 SWITCHED_SHUNT_ADJUSTMENT_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-204
1.163 TAP_ADJUSTMENT_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-205
1.164 TFLGNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-206
1.165 TIESNW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-207
1.166 TIEZNW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-208
1.167 TIMEAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-209
1.168 TLSTNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-210
1.169 TLTGAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-211
1.170 TPCHNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-214
1.171 TRANSMISSION_LINE_UNITS_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-216
iv
PSS/E-29
TABLE OF CONTENTS
1.172 TREEAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-217

1.173 TYSLAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-218
1.174 USERAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-219
1.175 VCHKNW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-220
1.176 VOLTAGE_INPUT_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-221
1.177 VOLTAGE_OUTPUT_API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-222
1.178 ZONENW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-223
1.179 ZONMNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-224
CHAPTER 2 - LOAD FLOW DATA CHANGING APIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1

2.1
2.2
2.3
2.4
2.5
2.6
2.7
2.8
2.9
2.10
2.11
2.12
2.13
2.14
2.15
2.16
2.17
2.18
2.19
2.20
2.21
2.22
2.23
2.24
2.25
2.26
2.27
2.28
2.29
2.30
2.31
2.32
2.33
2.34
2.35
PSS/E-29
Area Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1

Owner Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-3
Zone Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-4
Bus Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5
Non-Transformer Branch Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-6
Two-Winding Transformer Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-8
Three-Winding Transformer Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-11
Load Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-14
Plant Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-15
Machine Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-16
FACTS Device Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-18
Two-Terminal dc Line Link Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-20
Two-Terminal dc Line Converter Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-22
VSC dc Line Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-24
VSC dc Line Converter Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-25
Multi-Terminal dc Line. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-27
Multi-Terminal dc Line Converter Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-28
Multi-Terminal dc Line dc Bus Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-30
Multi-Terminal dc Line dc Link Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-32
Switched Shunt Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-33
Multi-Section Line Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-35
Multi-Section Line Edit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-36
Transformer Impedance Correction Table Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-37
Inter-Area Transfer Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-38
Solution Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-39
Change External Bus Number. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-40
Two-Line Case Title Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-41
Long Case Title Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-42
Bus Sequence Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-43
Branch Sequence Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-44
Two-Winding Transformer Sequence Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-45
Three-Winding Transformer Sequence Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-46
Machine Sequence Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-48
Switched Shunt Zero-Sequence Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-49
Zero-Sequence Mutual Coupling Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-50
TABLE OF CONTENTS
CHAPTER 3 - OPTIMAL POWER FLOW APIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

3.1
3.2
3.3
3.4
3.5
3.6
3.7
3.8
3.9
3.10
3.11
3.12
3.13
3.14
vi
Data Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

3.1.1 NEWOPF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Active Power Dispatch Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Adjustable Branch Reactances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
3.3.1 Individual Adjustable Branch Reactances . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
3.3.2 Adjustable Branch Reactance Data by Subsystem . . . . . . . . . . . . . . . . . . . . . 3-4
Adjustable Bus Loads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
3.4.1 Individual Bus Loads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
3.4.2 Bus Loads by Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
Adjustable Bus Load Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
Adjustable Bus Shunts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
3.6.1 Individual Adjustable Bus Shunts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
3.6.2 Adjustable Bus Shunts by Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10
Branch Flow Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13
3.7.1 Individual Branch Flow Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13
3.7.2 Branch Flow Constraints by Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14
Bus Voltage Magnitude Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18
3.8.1 Individual Bus Voltage Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18
3.8.2 Bus Voltage Constraints by Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19
Cost Curve Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22
3.9.1 Linear Cost Curve Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22
3.9.2 Quadratic Cost Curve Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22
3.9.3 Polynomial Cost Curve Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-23
Generator Dispatch Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25
3.10.1 Individual Generator Dispatch Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25
3.10.2 Generator Dispatch Data By Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25
Generation Reactive Capability Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-27
3.11.1 Individual Generation Reactive Capability Records. . . . . . . . . . . . . . . . . . . 3-27
3.11.2 Generation Reactive Capability Records by Subsystem . . . . . . . . . . . . . . . . 3-28
Generation Reserve Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30
3.12.1 Individual Generation Reserve Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30
3.12.2 Generator Reserve Records, by Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . 3-30
Interface Flow Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-32
3.13.1 Main Interface Flow Constraint Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-32
3.13.2 Remove all Participating Branches from an Interface . . . . . . . . . . . . . . . . . 3-33
3.13.3 Adding Participating Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-33
Linear Constraint Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-35
3.14.1 Main Linear Constraint Record. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-35
3.14.2 Remove all Participating Variables from Constraint Equation. . . . . . . . . . . 3-35
3.14.3 Voltage Magnitude Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-36
3.14.4 Voltage Angle Variable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-37
3.14.5 Active Power Dispatch Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-37
3.14.6 Reactive Power Generation Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-38
3.14.7 Transformer Tap Variable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-39
3.14.8 Branch Flow Constraint Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-39
3.14.9 Interface Flow Constraint Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-40
PSS/E-29
3.15
3.16
3.17
3.18
3.19
3.20
3.21
TABLE OF CONTENTS
3.14.10 Adjustable Bus Shunt Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-41

3.14.11 Switched Shunt Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-42
3.14.12 Adjustable Bus Load Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-42
List OPF Data (LSTONW) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-44
OPF Solution (NOPFNW) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-45
OPF Solution Options (OPTONW) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-46
Period Reserve Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-51
3.18.1 Main Period Reserve Constraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-51
3.18.2 Remove all Participating Reserve Units . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-51
3.18.3 Add Participating Reserve Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-52
Read Optimal Power Flow Data File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-53
Two-terminal dc Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-54
Write OPF Data File (RWOPNW) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-55
CHAPTER 4 - DYNAMICS SIMULATION APIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-1

4.1
4.2
4.3
4.4
4.5
4.6
4.7
4.8
4.9
4.10
4.11
4.12
4.13
4.14
4.15
4.16
4.17
4.18
4.19
4.20
4.21
4.22
4.23
4.24
4.25
4.26
4.27
4.28
4.29
4.30
PSS/E-29
CHSBNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-1
DOCUNW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-4
DYDANW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-5
RSTRNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-7
SNAPNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-8
LDLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-9
LDMOD_STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-10
LDMOD_STATUS2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-11
LDMOD_REMOVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-12
LDMOD_UNCONNECTED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-13
LDMOD_PACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-14
LDMOD_USER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-15
CHANGE_LDMOD_DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-16
ADD_LOAD_MODEL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-17
MLSTNW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-19
CHANGE_PLMOD_DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-20
ADD_PLANT_MODEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-21
PLMOD_STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-23
PLMOD_REMOVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-24
PLMOD_UNCONNECTED. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-25
PLMOD_PACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-26
PLMOD_USER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-27
PLMOD_CONSISTENCY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-28
RLLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-29
CHANGE_RLMOD_DATA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-30
ADD_RELAY_MODEL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-31
RLMOD_STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-32
RLMOD_REMOVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-33
RLMOD_UNCONNECTED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-34
RLMOD_PACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-35
vii
TABLE OF CONTENTS
4.31
4.32
4.33
4.34
4.35
4.36
RLMOD_USER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-36
SET_NETFRQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-37
SET_OSSCAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-38
SET_RELANG. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-39
SET_RELSCN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-40
SET_VLTSCN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-41
CHAPTER 5 - SUBSYSTEM DEFINITION APIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

5.1
5.2
5.3
5.4
5.5
System Initialization Definition APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

5.1.1 SBSINIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
Area Subsystem Definition APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
5.2.1 SBSACREATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
5.2.2 SBSASET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
5.2.3 SBSADELETE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Bus Subsystem Definition APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
5.3.1 SBSBCREATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
5.3.2 SBSBSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
5.3.3 SBSBSETA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
5.3.4 SBSBDELETE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
5.3.5 SBSBUSDSP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
5.3.6 SBSBSMEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
5.3.7 SBSBSRCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Owner Subsystem Definition APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
5.4.1 SBSOCREATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
5.4.2 SBSOSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
5.4.3 SBSODELETE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
Zone Subsystem Definition APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
5.5.1 SBSZCREATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
5.5.2 SBSZSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
5.5.3 SBSZDELETE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
CHAPTER 6 - SUBSYSTEM SELECTION APIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

6.1
6.2
viii
Area Subsystem Selection APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

6.1.1 SBSADEF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
6.1.2 SBSALINIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
6.1.3 SBSALAREA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
6.1.4 SBSALTERM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
6.1.5 SBSAVLA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
Bus Subsystem Selection APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4
6.2.1 SBSBDEF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4
6.2.2 SBSBLAREANB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5
6.2.3 SBSBLBUSNB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5
6.2.4 SBSBLZONENB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5
6.2.5 SBSBLOWNERNB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6
6.2.6 SBSVLAREA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6
6.2.7 SBSVLBUS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
6.2.8 SBSVLLOD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
PSS/E-29
6.3
6.4
6.5
PSS/E-29
TABLE OF CONTENTS
6.2.9 SBSVLMCBR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-8

6.2.10 SBSVLNUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-9
6.2.11 SBSVLOWNER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-9
6.2.12 SBSVLZONE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-10
6.2.13 SBSBLAINIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-10
6.2.14 SBSBLINIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-11
6.2.15 SBSBLAREA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-11
6.2.16 SBSBLBUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-12
6.2.17 SBSBLZONE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-12
6.2.18 SBSBLOWNER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-13
6.2.19 SBSBLTERM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-13
6.2.20 SBSGTBKV. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-13
6.2.21 SBSGTFLG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-14
Owner Subsystem Selection APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-15
6.3.1 SBSODEF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-15
6.3.2 SBSOLINIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-16
6.3.3 SBSOLOWNER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-16
6.3.4 SBSOLTERM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-16
6.3.5 SBSOVLO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-17
Zone Subsystem Selection APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-18
6.4.1 SBSZDEF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-18
6.4.2 SBSZLINIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-19
6.4.3 SBSZLZONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-19
6.4.4 SBSZLTERM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-19
6.4.5 SBSZVLZ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-20
Miscellaneous Subsystem APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-21
6.5.1 SBSRBDAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-21
6.5.2 SBSRBDBL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-21
6.5.3 SBSRBDOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-21
6.5.4 SBSRBDZL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-21
ix
This page intentionally left blank.
PSS/E-29
CHAPTER
1
POWER FLOW APIS
This document defines the Application Program Interfaces (APIs) to various engineering functions in
PSS/E. Eventually, all of PSS/Es functionality will be available through an API. For now, only those
activities that operate with area, bus, owner, and zone subsystems have been modified to use an API.
APIs are defined in two ways. The first method defines the use of the API within a FORTRAN or
C program. The API is described as a call to a subroutine with the number of arguments, their types,
and expected values defined. The API will return an IERR value, as defined, that will tell whether
invocation of the API was successful or not.
The second method defines the use of the API within a response file. This format would be produced
if a user executed the API from the Graphical User Interface (GUI) with ECHO on. This API can
be entered by hand in a text file and run through activity IDEV to automate the operation of the program, if so desired.
This document is used as a reference for both internal PTI developers and end users. The Fortran function calls described within are for use only by internal PTI developers. Their use by
end users is not supported. The BAT_ commands described are for use by the end user in writing
and modifying IDEV files created by PSS/E-28.
1.1 Default Information

To specify a "default" value for a particular array element when calling any of the API subroutines,
set an integer array element to the parameter BIGINT, which is defined in the MODULE PARAM4;
similarly, a "default" value for a real array element is specified by setting the appropriate REALAR
array element to the parameter BIGREL. When entering the corresponding "BAT_" command, use
FORTRAN free format input conventions (i.e., consecutive commas).
PSS/E-29
1-1
POWER FLOW APIS

ACCCAPI
1.2 ACCCAPI
This API executes activity ACCC. This API uses the default element specification as described in
Section 1.1. The API is invoked by the use of the statement:
ACCCAPI(TOL, OPTIONS, DFXFILE, ACCFILE, THRFILE, IERR, NERR)
or
BAT_ACCC
TOL OPTIONS(1) OPTIONS(2) OPTIONS(3) OPTIONS(4)
OPTIONS(5) OPTIONS(6) OPTIONS(7) DFXFILE ACCFILE THRFILE
where:
Real TOL
Is the mismatch tolerance (input).
Integer OPTIONS(7)
Is an array of seven elements specifying solution options (input). The

values are as follows:
OPTIONS(1), tap adjustment flag.
OPTIONS(1) = 0, disable.
OPTIONS(1) = 1, enable stepping adjustment.
OPTIONS(1) = 2, enable direct adjustment.
OPTIONS(2), area interchange adjustment flag.
OPTIONS(2) = 1, enable using tie line flows only in calculating area
interchange.
OPTIONS(2) = 2, enable using tie line flows and loads in calculating area
interchange.
OPTIONS(3), phase shift adjustment flag.
OPTIONS(3) = 1, enable.
OPTIONS(4), dc tap adjustment flag.
OPTIONS(5), switched shunt adjustment flag.
OPTIONS(6), solution method flag.
OPTIONS(6) = 0, FDNS.
OPTIONS(6) = 1, FNSL.
OPTIONS(7), non-divergent solution flag.
1-2
PSS/E-29
POWER FLOW APIS

ACCCAPI
Character DFXFILE*260
Is the name of Distribution Factor Data file (input).
Character ACCFILE*260
Is the name of Contingency Solution Output file (input).
Character THRFILE*260
Is the name of Load Throwover Data file; blank for none (input).
Integer IERR
Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid TOL value.
IERR = 2, invalid OPTIONS value.
IERR = 3, no DFAX file specified.
IERR = 4, error opening input file DFXFILE.
IERR = 5, no ACCC output file specified.
IERR = 6, error opening output file ACCFILE.
IERR = 7, error opening input file THRFILE.
IERR = 8, generators are "converted".
IERR = 9, working case has island without a swing bus.
Integer NERR
Is the number of error entries in PBUF02 (output).
PSS/E-29
1-3
POWER FLOW APIS

ALPHNW
1.3 ALPHNW
This API is used to print an alphabetically sorted table of all buses in a specified subsystem of the
working case. The API is invoked by use of the statement:
ALPHNW(SID, ALL, IERR)
or:
BAT_ALPH
SID
ALL
where:
Integer SID
Is a valid subsystem ID. Valid subsystem IDs range from 0 to 3. A subsystem must have been previously defined (input).
Integer ALL
Is the "all" buses or selected subsystem flag (input).

ALL = 1, process all buses.
ALL = 0, process only selected buses.
Integer IERR
Is the error return.

IERR = 1, either ALL or SID is in error.
1-4
PSS/E-29
POWER FLOW APIS

ANSIAPI
1.4 ANSIAPI
This API calculates fault currents according to the ANSI standard. To designate fault specification
data as part of the APIs calling sequence, INARG must be positive; to designate fault specification
data in an ANSI Fault Data input file, INARG must be zero and the filename specified as FILARG.
This API uses the default element specification as described in Section 1.1. The API is invoked by
the use of the statement:
ANSIAPI(OPTIONS, VALUES, INARG, BUSARY, VLTARY, CPTARY, FILARG,
IERR, NERR)
or
BAT_ANSI
VALUES(2)
VLTARY(1)
OPTIONS(1) OPTIONS(2) OPTIONS(3) VALUES(1)

VALUES(3) VALUES(4) INARG BUSARY(1) BUSARY(INARG)
VLTARY(INARG) CPTARY(1) CPTARY(INARG) FILARG
where:
Integer OPTIONS(3)
Is an array of three elements specifying solution and reporting options

(input). The values are as follows:
OPTIONS(1), impedance correction option for transformers in the zero
sequence network:
OPTIONS(1) = 0, do not apply transformer impedance correction in zero
sequence.
OPTIONS(1) = 1, apply transformer impedance correction in zero
sequence.
OPTIONS(2), set of ANSI decrement factors to use:
OPTIONS(2) = 0, account for DC decrement only (use ANSI table 3).
OPTIONS(2) = 1, account for AC and DC decrements (use ANSI tables 1
and 2).
OPTIONS(3), output option:
OPTIONS(3) = 0, report format (blank delimited output fields).
OPTIONS(3) = 1, spreadsheet input format (comma delimited output fields).
Real VALUES(4)
Is an array of four elements specifying divisors for calculating resistances

of network elements whose resistance is zero in the working case (input).
VALUES(1), used for branches in the positive sequence network.
VALUES(2), used for machines in the positive sequence network.
VALUES(3), used for branches in the zero sequence network.
VALUES(4), used for machines in the zero sequence network.
Integer INARG
Is the fault specification option (input):

INARG = 0, fault specifications specified in input file.
INARG = >0, fault specifications specified in calling sequence.
PSS/E-29
1-5
POWER FLOW APIS

ANSIAPI
Integer BUSARY
Is an array of INARG elements specifying faulted buses; ignored if

INARG = 0 (input).
Real VLTARY
Is an array of INARG elements specifying maximum operating voltages in

pu; ignored if INARG = 0 (input).
Real CPTARY
Is an array of INARG elements specifying contact parting times in seconds; ignored if INARG = 0 (input).
Character FILARG*260 Is the filename of ANSI Fault Data input file; ignored if INARG > 0 (input).
Integer IERR

IERR = 1, no case in memory.
IERR = 2, sequence data not in case.
IERR = 4, invalid VALUES value.
IERR = 5, invalid INARG value.
IERR = 6, error opening file FILARG.
Integer NERR
1-6
PSS/E-29
POWER FLOW APIS

AREA_INTERCHANGE_CONTROL_API
1.5 AREA_INTERCHANGE_CONTROL_API
This API is used to set the value of the area interchange control option setting to either "disabled",
"enabled with tie lines only" or "enabled with tie lines and loads". The API is invoked by the use of
the statement:
CALL AREA_INTERCHANGE_CONTROL_API(IVAL, IOCODE, IERR, NERR)
or
BAT_AREA_INTERCHANGE_CONTROL
IVAL
where:
Integer IVAL
Is the value of the option setting (input if IOCODE is 0 or BAT_ command,

output if IOCODE is 1).
IVAL = 0, disabled.
IVAL = 1, enabled with interchange determined from tie lines only.
IVAL = 2, enabled with interchange determined from tie lines and loads.
Integer IOCODE
Indicates the operation mode of the API (input).

IOCODE = 0, set the option setting to the value specified in IVAL.
IOCODE = 1, return the current value of the option setting in IVAL.
Integer IERR

IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.
Integer NERR
PSS/E-29
1-7
POWER FLOW APIS

AREANW
1.6 AREANW
This API is used to provide a tabulation by area interchange of the desired area net interchange. The
API is invoked by the use of the statement:
AREANW(SID, ALL, IERR)
or:
BAT_AREA
SID
ALL
where:
Integer SID
Is a valid subsystem ID. Valid subsystem IDs range from 0 to 3. A subsystem

must have been previously defined (input).
Integer ALL
Is the "all" areas or selected subsystem flag (input).

ALL = 1, process all areas.
ALL = 0, process only selected areas.
Integer IERR

1-8
PSS/E-29
POWER FLOW APIS

ARNMNW
1.7 ARNMNW
This API is used to reassign the buses and loads in a selected subsystem of the working case from
their original area to a designated area. The API is invoked by the use of the statement:
ARNMNW(SID, ALL, STATUS, IANEW, IERR)
or:
BAT_ARNM
SID
ALL
STATUS(1)
STATUS(2)
IANEW
where:
Integer SID

Integer ALL

Integer STATUS(2)
Is an array of two elements. The values are as follows:

STATUS(1) = 1, change bus areas to IANEW; otherwise = 0.
STATUS(2) = 1, change load areas to IANEW; otherwise = 0.
Integer IANEW
Is the new area to assign the selected buses to. IANEW must be between 1 and
AREAS.
Integer IERR

IERR = 2, STATUS is in error.
IERR = 3, IANEW is not between 1 and AREAS.
PSS/E-29
1-9
POWER FLOW APIS

ASCCNW
1.8 ASCCNW
This API is used to apply a series of faults at various locations in the working case. The API is
invoked by the use of the statement:
ASCCNW(SID, ALL, STATUS, RFILE, FFILE, IERR)
or:
BAT_ASCC
SID ALL STATUS(1) STATUS(2) STATUS(3) STATUS(4)
STATUS(5) STATUS(6) STATUS(7) STATUS(8) STATUS(9) STATUS(10)
RFILE FFILE
where:
Integer SID

Integer ALL

Integer STATUS(10)
Is an array of 10 elements. The values are as follows.

STATUS(1), three-phase line-to-ground fault calculation.
STATUS(1) = 0, ignore calculation.
STATUS(1) = 1, perform calculation.
STATUS(2), line-out fault calculation.
STATUS(3), line-end fault calculation.
STATUS(4), flat-condition fault calculation.
STATUS(5), double-precision fault calculation.
STATUS(6), output option.
STATUS(6) = 1, full output at home bus "N" levels away.
STATUS(6) = 2, full output at home bus, summary "N" levels away.
STATUS(6) = 3, fault current summary table.
1-10
PSS/E-29
POWER FLOW APIS

ASCCNW
STATUS(7), number of levels for contribution output, if STATUS(6) = 1

or 2.
STATUS(7) >= 0.
STATUS(8), branch quantity output code for line to ground faults.
STATUS(8) = 0, A phase.
STATUS(8) = 1, 3 * IO.
STATUS(8) = 2, both.
STATUS(9), block dc lines option.
STATUS(9) = 0, blocked.
STATUS(9) = 1, loading represented.
STATUS(10), transformer impedance correction.
STATUS(10) = 0, do not apply to zero sequence.
STATUS(10) = 1, apply to zero sequence.
Character RFILE*260 Is the Relay Output Data file.
Character FFILE*260
Is the Fault Control Input file.
Integer IERR

IERR = 3, RFILE and/or FFILE is in error.
IERR = 4, no sequence data in the case.
PSS/E-29
1-11
POWER FLOW APIS

BASE_FREQUENCY_API
1.9 BASE_FREQUENCY_API
This API is used to set the value of the base frequency option setting. The API is invoked by the use
of the statement:
CALL BASE_FREQUENCY_API(RVAL, IOCODE, IERR, NERR)
or
BAT_BASE_FREQUENCY
RVAL
where:
Real IVAL

Integer IOCODE

IOCODE = 0, set the option setting to the value specified in RVAL.
IOCODE = 1, return the current value of the option setting in RVAL.
Integer IERR

IERR = 1, invalid RVAL value.
Integer NERR
1-12
PSS/E-29
POWER FLOW APIS

BGENNW
1.10 BGENNW
This API is used to convert the mismatch at boundary buses to equivalent load and/or generation.
It is intended to be used following the removal of a subsystem from a solved working case, with the
flows to the deleted subsystem replaced by load and/or generation at those retained buses that were
directly connected to the removed subsystem. The API is invoked by the use of the statement:
BGENNW(SID, ALL, STATUS, IERR)
or:
BAT_BGEN
SID
ALL
STATUS
where:
Integer SID

Integer ALL

Integer STATUS
Is the type of boundary condition modification to be used.

STATUS = 0, generator for inflow; load for outflow.
STATUS = 1, all equivalent generators.
STATUS = 2, all equivalent loads.
Integer IERR

PSS/E-29
1-13
POWER FLOW APIS

BKDYNW
1.11 BKDYNW
This API is used to calculate and report circuit breaker interrupting duty for 3-phase faults at all
buses in a specified subsystem of the working case. The API is invoked by the use of the statement:
BKDYNW(SID, ALL, APIOPT, LVLBAK, FLTTIM, BFILE, FFILE, IERR)
or:
BAT_BKDY
SID
ALL
APIOPT
LVLBAK
FLTTIM
BFILE
FFILE
where:
Integer SID

Integer ALL

Integer APIOPT
Is the mode of operation in the API.

APIOPT = 1, fault selections specified in selected subsystem.
APIOPT = 2, fault selections specified in FFILE.
Integer LVLBAK
Is the levels back for contributions output. LVLBAK >= 0.
Real FLTTIM
Is the default Fault Duty time FLTTIM >= 0.0.
Character BFILE*260 Is the Breaker Duty Data file.

Character FFILE*260
Is the Fault Specification Input file.
Integer IERR

IERR = 2, APIOPT is in error.
IERR = 3, LVLBAL or FLTTIM is in error.
IERR = 4, BFILE or FFILE is in error.
IERR = 5, generators are not converted.
1-14
PSS/E-29
POWER FLOW APIS

BMATAPI
1.12 BMATAPI
This API executes activity BMAT. This API uses the default element specification as described in
BMATAPI(OPTIONS, OUT, OFILE, FILARG, IERR, NERR)
or
BAT_BMAT
FILARG
OPTIONS(1)
OPTIONS(2)
OPTIONS(3)
OUT
OFILE
where:
Integer OPTIONS(3)
Is an array of three elements specifying output options (input). The values

are as follows:
OPTIONS(1), axis flag.
OPTIONS(1) = 0, plant axes only.
OPTIONS(1) = 1, axes for all machines.
OPTIONS(2), region flag.
OPTIONS(2) = 0, zones as regions.
OPTIONS(2) = 1, areas as regions.
OPTIONS(3), resistances on branches with circuit identifier 99.
OPTIONS(3) = 0, exclude.
OPTIONS(3) = 1, include.
Integer OUT
Is the output selection option (input).

OUT = 0, output to the data file specified by OFILE.
OUT = 1, output to the progress window.
Character OFILE*260 Is the filename of the output file (input).

Character FILARG*260 Is the filename of the off-base Saved Case File (input)
Integer IERR

IERR = 2, invalid value of OUT.
IERR = 3, error opening output file OFILE.
IERR = 4, error opening input file FILARG.
IERR = 5, in-service phase shifter in case.
Integer NERR
PSS/E-29
1-15
POWER FLOW APIS

BRCHNW
1.13 BRCHNW
This API is used to tabulate those branches whose impedances or other characteristics are such that
they may be detrimental to the rate of convergence of one or more of the power flow solution activities. The API is invoked by the use of the statement:
BRCHNW(SID, ALL, DOTEST, TOLVAL, IERR)
or:
BAT_BRCH
DOTEST(5)
TOLVAL(1)
TOLVAL(7)
SID ALL DOTEST(1) DOTEST(2) DOTEST(3) DOTEST(4)

DOTEST(6) DOTEST(7) DOTEST(8) DOTEST(9) DOTEST(10)
TOLVAL(2) TOLVAL(3) TOLVAL(4) TOLVAL(5) TOLVAL(6)
where:
Integer SID

Integer ALL

Integer DOTEST(10)
Is an array of ten elements. Each element is used to determine whether a specific

branch check should be performed. DOTEST[I] = 1, the specific branch check
is performed. DOTEST[I] = 0, the specific branch check is not performed.
DOTEST[1], check small impedances.
DOTEST[2], check large impedances.
DOTEST[3], check R/X ratios.
DOTEST[4], check negative impedances.
DOTEST[5], check Xmax/Xmin for each bus.
DOTEST[6], check charging.
DOTEST[7], check parallel transformers.
DOTEST[8], check high tap ratios.
DOTEST[9], check low tap ratios.
DOTEST[10], check missing zero sequence lines.
Real TOLVAL(7)
Is an array of seven elements. Each element contains a tolerance/limit value

used in one of the branch checks.
TOLVAL[1] > 0, reactance lower limit.
TOLVAL[2] > 0, reactance upper limit.
TOLVAL[3] > 0, R/X threshold.
TOLVAL[4] >= 10, Xmax/Xmin threshold.
TOLVAL[5] >= 0, charging upper limit.
TOLVAL[6] >.8, high tap ratio limit.
TOLVAL[7] > 0 and < 1.2, low tap ratio limit.
1-16
PSS/E-29
POWER FLOW APIS

BRCHNW
Integer IERR
PSS/E-29

IERR = 2, one of the TOLVAL values is in error.
1-17
POWER FLOW APIS

BSNMNW
1.14 BSNMNW
This API is used to change the bus numbers of selected network buses in the working case and retain
a tabulation, in file form, of bus number changes made. The API is invoked by the use of the
statement:
BSNMNW(SID,ALL, OPT, STATUS, BUSRNG, OLDNAM, TFILE, OUT, OFILE, IERR)
or:
BAT_BSNM
TFILE OUT
SID ALL
OFILE
OPT
STATUS
BUSRNG(1)
BUSRNG(2)
OLDNAM
where:
Integer SID

Integer ALL

Integer OPT
Is the method used to renumber the buses.

OPT = 0, initialize for renumbering.
OPT = 1, renumber buses based on old name/new number pairs.
OPT = 11, renumber using name translation file.
OPT = 2, renumber buses based on old number/new number pairs.
OPT = 12, renumber buses using number translation file.
OPT = 3, pack all buses in specified low/high pairs.
OPT = 4, renumber buses based on selected subsystem.
OPT = 5, renumber all buses.
OPT = 15, renumber all buses blocking by area.
OPT = 25, apply blocking by area changes.
OPT = 35, cancel blocking by area changes.
OPT = 7, cleanup from renumbering.
Integer STATUS
STATUS has different values/meanings depending on the value of OPT.

If OPT = 4:
STATUS = 0, new bus number range is provided.
STATUS = 1, bus number offset is provided.
If OPT = 15:
STATUS = area, where the area number is the area to block buses for.
STATUS must be between 1 and AREAS.
1-18
PSS/E-29
POWER FLOW APIS

BSNMNW
Integer BUSRNG(2)
Is an array of two elements. BUSRNG has different values/meanings

depending on the value of OPT.
If OPT = 1:
BUSRNG(1), is the new bus number.
If OPT = 2:
BUSRNG(1), is the old bus number.
BUSRNG(2), is the new bus number.
If OPT = 3:
BUSRNG(1), is the bus number at which to start packing sequentially.
BUSRNG(2), is the bus number at which to end packing sequentially.
If OPT = 4 and STATUS = 0:
BUSRNG(1), is the starting bus number for the range into which the subsystem is to be renumbered.
BUSRNG(2), is the ending bus number for the range into which the subsystem is to be renumbered.
If OPT = 4 and STATUS = 1:
BUSRNG(1), is amount by which all buses in the specified subsystem are
offset.
If OPT = 5:
BUSRNG(1), bus number at which to start renumbering all buses in the
working case. Buses are resequenced by increments of 1.
If OPT = 15:
BUSRNG(1), is the starting bus number for the range into which the area
is to be renumbered.
BUSRNG(2), is the ending bus number for the range into which the area is
to be renumbered.
Character OLDNAM*16 Is the name of the bus to be renumbered. This must be an existing bus
name. OLDNAM is only used If OPT = 1 and TFILE = , that is, bus
name translation has been specified and no translation file has been
provided.
Character TFILE*260 Is the bus name/number translation file. This file is only used if OPT = 1 or
OPT = 2. Data in the translation file must be in the form specified in the PSS/E
Program Operation Manual.
Integer OUT
PSS/E-29
Is the output option selection.

OUT = 0, output to a data file specified by OFILE.
OUT = 2, no output.
1-19
POWER FLOW APIS

BSNMNW
Character OFILE*260 Is the bus translation output file.

Integer IERR

If OPT = 0:
IERR = 7, OUT is in error.
IERR = 8, error opening OFILE.
If OPT = 1 or 2:
IERR = 9, last OPT not 0.
If OPT = 11 or 12:
IERR = 2, error opening TFILE.
If OPT = 3:
IERR = 9, last OPT not 0 or 3.
IERR = 5, bus range error, BUSRNG(1) <= 0, or BUSRNG(2) > HIBUS,
or BUSRNG(1) > BUSRNG(2).
If OPT = 4:
IERR = 15, BUSRNG(1) = 0.
IERR = 5, bus range error.
If OPT = 5:
IERR = 10, invalid starting bus number.
IERR = 11, not enough numbers between BUSRNG(1) and 99997.
If OPT = 15:
IERR = 12, too many OPT 15 calls.
IERR = 13, STATUS not equal to next area expected.
IERR = 5, range error or ranges overlap.
If OPT = 25:
IERR = 14, not enough OPT 15 calls.
If OPT = 35:
1-20
PSS/E-29
POWER FLOW APIS

BUS_INPUT_API
1.15 BUS_INPUT_API
This API is used to set the value of the bus input option setting to either "numbers" or "names". The
CALL BUS_INPUT_API(IVAL, IOCODE, IERR, NERR)
or
BAT_BUS_INPUT
IVAL
where:
Integer IVAL

IVAL = 0, bus numbers.
IVAL = 1, extended bus names.
Integer IOCODE

Integer IERR

Integer NERR
PSS/E-29
1-21
POWER FLOW APIS

BUS_OUTPUT_API
1.16 BUS_OUTPUT_API
This API is used to set the value of the bus output option setting to either "numbers" or "names".
The API is invoked by the use of the statement:
CALL BUS_OUTPUT_API(IVAL, IOCODE, IERR, NERR)
or
BAT_BUS_OUTPUT
IVAL
where:
Integer IVAL

IVAL = 0, bus numbers.
IVAL = 1, extended bus names.
Integer IOCODE

Integer IERR

Integer NERR
1-22
PSS/E-29
POWER FLOW APIS

BUSNAPI
1.17 BUSNAPI
This API executes activity BUSN. The API is invoked by the use of the statement:
BUSNAPI(BUSLO, BUSHI, IERR, NERR)
or
BAT_BUSN
BUSLO
BUSHI
where:
Integer BUSLO
Is the low limit of bus number range (input).
Integer BUSHI
Is the high limit of bus number range (input).
Integer IERR

IERR = 1, BUSLO < 1.
IERR = 2, BUSHI < BUSLO.
Integer NERR
PSS/E-29
1-23
POWER FLOW APIS

CASENW
1.18 CASENW
This API is used to open a PSS/E Saved Case file. The API is invoked by the use of the statement:
CASENW(SFILE, IERR)
or:
BAT_CASE
SFILE
where:
Character SFILE*260
Is the PSS/E Saved Case. If SFILE is "*", CASENW will attempt to reopen
the last Saved Case file opened. If none exists, CASENW will return an IERR
value.
Integer IERR

IERR = 1, error opening SFILE.
IERR = 2, error reading from SFILE.
1-24
PSS/E-29
POWER FLOW APIS

CMPRNW
1.19 CMPRNW
This API is used to provide a tabulation of certain case totals, as contained in the working case, with
those of a designated Saved Case. Either system totals, area totals, owner totals, or zone totals may
be compared. The API is invoked by the use of the statement:
CMPRNW(SID, APIOPT, STATUS, THRSH, CFILE, IERR)
or:
BAT_CMPR
STATUS(4)
SID
THRSH
APIOPT
CFILE
STATUS(1)
STATUS(2)
STATUS(3)
where:
Integer SID

Integer APIOPT

APIOPT = 1, initialize system for system, area, owner, zone totals.
APIOPT = 2, calculate system, area, owner, zone totals.
APIOPT = 3, postprocessing of system, area, owner, zone totals.
Integer STATUS(4)
Is an array of four elements. The value of each element is as follows.

STATUS(1), is the tabulation method.
STATUS(1) = 0, tabulate system totals.
STATUS(1) = 1, tabulate area totals.
STATUS(1) = 2, tabulate owner totals.
STATUS(1) = 3, tabulate zone totals.
STATUS(2), is the units for the difference threshold.
STATUS(2) = 0, threshold in engineering units.
STATUS(2) = 1, threshold in percent.
STATUS(3), is the quantity to be compared.
STATUS(3) = 1, compare generation.
STATUS(3) = 2, compare load.
STATUS(3) = 3, compare losses.
STATUS(3) = 4, compare mismatch.
STATUS(3) = 5, compare interchange; not valid for STATUS(1) = 2.
STATUS(4), is the file to restore upon completion.
STATUS(4) = 0, restore the working case.
STATUS(4) = 1, restore the comparison file to the working case.
Real THRSH
PSS/E-29
Is the difference threshold, in either engineering units or a percent, based on

the value of STATUS(2).
1-25
POWER FLOW APIS

CMPRNW
Character CFILE*260 Is the Saved Case file to be compared against the working case.
Integer IERR
1-26

IERR = 1, SID is in error.
IERR = 4, error opening CFILE.
PSS/E-29
POWER FLOW APIS

CNTBNW
1.20 CNTBNW
This API is used to tabulate the voltage setpoints or desired bands of voltage-controlling equipment
in the working case, and allows the user to specify new scheduled voltages. The API is invoked by
CNTBNW(SID, ALL, APIOPT, STATUS, NEXT, BUS, CKT, V, IERR)
or:
BAT_CNTB
V(1) V(2)
SID
ALL
APIOPT STATUS(1)
STATUS(2)
STATUS(3)
where:
Integer SID

Integer ALL
Is the "all" buses or selected buses subsystem flag (input).

Integer APIOPT

APIOPT = 1, initialize system.
APIOPT = 2, specify voltage setpoint.
APIOPT = 3, specify voltage band for load drop compensating transformer.
Integer BUS(3)
Is a returned array of three elements described below.
When APIOPT = 1, initialize.

Integer STATUS(3)
Is an array of three elements. They are used to control reporting options.

STATUS(1) = 0, list subsystem controlled buses with conflicts.
STATUS(1) = 1, list all subsystem controlled buses.
STATUS(2) = 0, report at OPENed output devices.
STATUS(2) = 1, list in progress area and allow voltage schedule change.
STATUS(3) = 0, process all controlling elements and controlled buses.
STATUS(3) = 1, process active controlling elements and controlled buses.
Real V(2)
Is an array of two elements.

V(1), VMIN, not used except for ECHO.
V(2), VMAX, not used except for ECHO.
Integer IERR

PSS/E-29
1-27
POWER FLOW APIS

CNTBNW
Integer NEXT
Is returned as the next APIOPT value expected by the API.

NEXT = 1, done with this execution of CNTBNW.
NEXT = 2, change voltage setpoint/schedule.
BUS(1) returned as controlled bus whose voltage schedule may be
changed.
V(1) initial value.
NEXT = 3, change VMIN, VMAX of load drop compensating
transformer.
changed.
BUS(2) returned as "from bus" of the transformer.
BUS(3) returned as "to bus" of the transformer.
V(1) returned as VMIN.
V(2) returned as VMAX.
Character CKT*2
Is returned as the circuit ID of the transformer returned in BUS(2) and

BUS(3) when NEXT returned as 3.
When APIOPT = 2, specify voltage setpoint.

Integer STATUS(3)

STATUS(1) = 0, no change.
STATUS(1) = 1, new setpoint in V(1).
STATUS(2), not used except for ECHO.
Real V(2)

V(1), new setpoint.
V(2), VMAX not used except for ECHO.
Integer IERR

IERR = 3, V(1) <= 0.5 or V(1) >= 1.5.
IERR = 5, unexpected APIOPT value.
1-28
PSS/E-29
POWER FLOW APIS

CNTBNW
Integer NEXT

changed.
V(1) initial value.
NEXT = 3, change VMIN, VMAX of load drop compensating
transformer.
changed.
When APIOPT = 3, specify voltage band for load drop compensating transformer.
Integer STATUS(3)

STATUS(1) = 1, new voltage band in V(1) and V(2).
Real V(2)

V(1), VMIN.
V(2), VMAX.
Integer IERR

IERR = 3, V(1) >= V(2).
IERR = 5, unexpected APIOPT value.
PSS/E-29
1-29
POWER FLOW APIS

CNTBNW
Integer NEXT

changed.
V(1) initial value.
NEXT = 3, change voltage band, VMIN, VMAX of load drop compensating transformer.
BUS(1) returned as controlled bus whose voltage band may be changed.
1-30
PSS/E-29
POWER FLOW APIS

CONNECTIVITY_CHECK_API
1.21 CONNECTIVITY_CHECK_API
This API is used to set the value of the solution connectivity checking option setting to either "no"
or "yes". The API is invoked by the use of the statement:
CALL CONNECTIVITY_CHECK_API(IVAL, IOCODE, IERR, NERR)
or
BAT_CONNECTIVITY_CHECK
IVAL
where:
Integer IVAL

IVAL = 0, no solution connectivity check before power flow solutions.
IVAL = 1, perform solution connectivity check before power flow
solutions.
Integer IOCODE

Integer IERR

Integer NERR
PSS/E-29
1-31
POWER FLOW APIS

CONGAPI
1.22 CONGAPI
This API executes activity CONG. The API is invoked by the use of the statement:
CONGAPI(OPT, IERR, NERR)
or
BAT_CONG
OPT
where:
Integer OPT
Is the machine impedance option (input).

OPT = 0, use ZSORCE.
OPT = 1, use ZPOS.
Integer IERR

IERR = 0, no error.
IERR = 1, invalid value of OPT.
IERR = 2, generators are already converted.
Integer NERR
1-32
PSS/E-29
POWER FLOW APIS

CONLNW
1.23 CONLNW
This API is used to convert the constant MVA load for a selected grouping of network loads to a
specified mixture of the constant MVA, constant current, and constant admittance load characteristics. The API is invoked by the use of the statement:
CONLNW(SID, ALL, APIOPT, STATUS, LOADIN, RLODS, IERR)
or:
BAT_CONL
LOADIN(2)
SID ALL APIOPT STATUS(1)

LOADIN(3) LOADIN(4)
STATUS(2) LOADIN(1)
where:
Integer SID

Integer ALL

Integer APIOPT

APIOPT = 1, initialize system for load conversion.
APIOPT = 2, convert loads.
APIOPT = 3, postprocessing of load conversion.
Integer STATUS(2)
Is an array of two elements. The value of each element is as follows.

STATUS(1), is the method of conversion.
STATUS(1) = 0, convert loads.
STATUS(1) = 1, reconstruct loads using present voltage.
STATUS(1) = 2, reconstruct loads using unity voltage.
STATUS(2), is a special OPF bus type code flag.
STATUS(2) = 0, all buses in subsystem.
STATUS(2) = 1, only type 1 buses in subsystem.
STATUS(2) = 2, only type 2 and 3 buses in subsystem.
Real LOADIN(4)
Is an array of four elements. The value of each element is as follows.

LOADIN(1), is the constant, I, for real power.
LOADIN(2), is the constant, G, for real power.
LOADIN(3), is the constant, I, for reactive power.
LOADIN(4), is the constant, B, for reactive power.
Integer RLODS
Is returned as the number of unconverted loads remaining in the working

case. If the value is nonzero and the remaining loads are to be converted, the
API is called again with ALL = 1 and APIOPT = 2.
PSS/E-29
1-33
POWER FLOW APIS

CONLNW
Integer IERR
1-34

PSS/E-29
POWER FLOW APIS

DC_TAP_ADJUSTMENT_API
1.24 DC_TAP_ADJUSTMENT_API
This API is used to set the value of the dc tap adjustment option setting to either "disabled" or
"enabled". The API is invoked by the use of the statement:
CALL DC_TAP_ADJUSTMENT_API(IVAL, IOCODE, IERR, NERR)
or
BAT_DC_TAP_ADJUSTMENT
IVAL
where:
Integer IVAL

IVAL = 0, disabled.
IVAL = 1, enabled.
Integer IOCODE

Integer IERR

Integer NERR
PSS/E-29
1-35
POWER FLOW APIS

DCCCAPI
1.25 DCCCAPI
This API executes activity DCCC. The API is invoked by the use of the statement:
DCCCAPI(OPTIONS, TOLS, DFXFILE, IERR, NERR)
or:
BAT_DCCC
OPTIONS(5)
OPTIONS(1) OPTIONS(2) OPTIONS(3) OPTIONS(4)

OPTIONS(6) TOLS(1) TOLS(2) TOLS(3) DFXFILE
where:
Integer OPTIONS(6)
Is an array of six elements specifying calculation and reporting options

(input). The value of each element is as follows.
OPTIONS(1), contingency case rating set.
OPTIONS(1) = 1, RATEA.
OPTIONS(1) = 2, RATEB.
OPTIONS(1) = 3, RATEC.
OPTIONS(2), base case line flow code.
OPTIONS(2) = 0, dc base case.
OPTIONS(2) = 1, ac base case.
OPTIONS(3), output format code.
OPTIONS(3) = 0, summary output.
OPTIONS(3) = 1, full output.
OPTIONS(4), exclude cases with no overloads from the summary
report.
OPTIONS(4) = 0, no.
OPTIONS(4) = 1, yes.
OPTIONS(5), convert MVA ratings to estimated MW ratings.
OPTIONS(5) = 0, no.
OPTIONS(6), code to abort if MW mismatch exceeds TOLS(1).
OPTIONS(6) = 0, abort.
OPTIONS(6) = 1, continue.
Real TOLS(3)
1-36
Is an array of three elements specifying tolerances and thresholds (input).

The value of each element is as follows.
TOLS(1), required MW mismatch tolerance for continuing.
TOLS(2), percent of rating for reporting an element as overload.
TOLS(3), minimum flow change for including element in summary
report.
PSS/E-29
POWER FLOW APIS

DCCCAPI
Character DFXFILE*260 Is the name of Distribution Factor Data input file (input).
Integer IERR

IERR => 0, no error occurred.
IERR => 1, no case in memory.
IERR => 2, invalid OPTIONS value.
IERR => 3, invalid TOLS value.
IERR => 4, no DFAX output file specified.
IERR => 5, subroutine GETLOS error (generators are "converted" or
swingless island.
IERR => 6, subroutine INPROC error.
Integer NERR
PSS/E-29
1-37
POWER FLOW APIS

DCLFNW
1.26 DCLFNW
This API is used to apply the dc analogy network solution algorithm to the network modeled in the
working case. The API is invoked by the use of the statement:
DCLFNW(SID, ALL, STATUS, BRNCH, CKT, IERR)
or:
BAT_DCLF
BRNCH(2)
SID ALL STATUS(1)

BRNCH(3) CKT
STATUS(2)
STATUS(3)
BRNCH(1)
where:
Integer SID

Integer ALL

Integer STATUS(3)
Is an array of three elements. The value of each element is as follows.

STATUS(1), is rating used in tabulating the report.
STATUS(1) = 1, RATEA.
STATUS(1) = 2, RATEB.
STATUS(1) = 3, RATEC.
STATUS(2), is the voltage that should be saved.
STATUS(2) = 0, original voltages.
STATUS(2) = 1, base case dc load flow voltages.
STATUS(2) = 2, change case dc load flow voltages.
STATUS(3), is status of the changed branch upon completion.
STATUS(3) = 0, leave unchanged.
STATUS(3) = 1, save changed status.
Integer BRNCH(2)
Is an array of two elements. The use of each element is as follows. The values
can both be zero is no branch is to be changed for the solution.
BRNCH(1), is the from bus of the branch whose status is to be changed for
the solution.
BRNCH(2), is the to bus of the branch whose status is to be changed for
the solution.
BRNCH(3), is the third bus connected by a three-winding transformer, or
zero for a nontransformer branch or a two-winding transformer.
Character CKT*2
1-38
Is the circuit ID of the branch whose status is to be changed for the solution.
PSS/E-29
Integer IERR
PSS/E-29
POWER FLOW APIS

DCLFNW

IERR = 3, the branch to be changed does not exist.
IERR = 4, the branch is a multisection line, and multisection line reporting
is off.
IERR = 5, closing a multisection line is not allowed.
IERR = 6, cannot return a type 4 bus to service.
IERR = 7, closing a three-winding transformer is not allowed.
1-39
POWER FLOW APIS

DFAXAPI
1.27 DFAXAPI
This API executes activity DFAX. The API is invoked by the use of the statement:
DFAXAPI(OPTIONS, SUBFILE, MONFILE, CONFILE, DFXFILE, IERR, NERR)
or:
BAT_DFAX
DFXFILE
OPTIONS(1)
OPTIONS(2)
SUBFILE
MONFILE
CONFILE
where:
Integer OPTIONS(2)
Is an array of two elements specifying calculation options (input). The value

of each element is as follows.
OPTIONS(1), distribution factor option flag.
OPTIONS(1) = 0, do not calculate distribution factors (i.e., DFAX,AC).
OPTIONS(1) = 1, calculate distribution factors.
OPTIONS(2), monitored element sorting flag.
OPTIONS(2) = 0, do not sort (i.e., leave in Monitored Element File order).
OPTIONS(2) = 1, sort.
Character SUBFILE*260 Is the name of the Subsystem Description Data input file; blank for none
(input).
Character MONFILE*260Is the name of Monitored Element Data input file (input).
Character CONFILE*260 Is the name of Contingency Description Data input file (input).
Integer IERR

IERR = 3, generators are converted.
IERR = 4, no DFAX output file specified.
IERR = 5, error opening output file DFXFILE.
IERR = 6, error opening input file SUBFILE.
IERR = 7, no Monitored Element input file specified.
IERR = 8, error opening input file MONFILE.
IERR = 9, fatal error reading input file.
IERR = 10, no Contingency Description input file specified.
IERR = 11, error opening input file CONFILE.
Integer NERR
1-40
PSS/E-29
POWER FLOW APIS

DFTIAPI
1.28 DFTIAPI
This API performs a case comparison of tie lines (activity DFTI). It must be referenced using one
of the following procedures:
One reference with APIOPT=1, followed by any number of references with

APIOPT=2, followed by one reference with APIOPT=3.
One reference with APIOPT=0. This automatically combines the processing of one
APIOPT 1 reference, followed by one APIOPT 2 reference, followed by one APIOPT
3 reference.
This API uses the default element specification as described in Section 1.1. The API is invoked by
DFTIAPI(SID, APIOPT, STATUS, THRESH, CFILE, SEQFLG, IERR, NERR)
or
BAT_DFTI
STATUS(4)
SID APIOPT STATUS(1)

STATUS(5) THRESH CFILE
STATUS(2)
STATUS(3)
where:
Integer SID
Is the valid subsystem ID (0 to 3). Subsystem SID must have been previously defined (input).
Integer APIOPT
Is the mode of operation of DFTIAPI (input).

APIOPT = 0, initialize for case comparison, perform the comparison specified by STATUS(4), and do post-processing clean up.
APIOPT = 1, initialize for case comparison.
APIOPT = 2, perform a comparison.
APIOPT = 3, post-processing clean up.
Integer STATUS(5)
Is an array of five elements specifying comparison options (input). The

STATUS(1), defines the working case content following an APIOPT=0 or
3 reference.
STATUS(1) = 0, original working case.
STATUS(1) = 1, Saved Case specified in CFILE.
STATUS(2), flag for method of considering buses in the two cases to be
the same bus.
STATUS(2) = 0, same bus numbers.
STATUS(2) = 1, same extended bus names.
STATUS(2) = 2, same bus numbers and extended bus names.
PSS/E-29
1-41
POWER FLOW APIS

DFTIAPI
STATUS(3), flag for specifying THRESH.

STATUS(3) = 0, engineering units.
STATUS(3) = 1, percent.
STATUS(4), code for the comparison to be performed:
= 1, branch status
= 3, line shunts
= 5, metered end
= 7, transformers
= 9, flows (from and to buses
= 11, zero sequence R, X, B
= 13, transformer grounding codes
= 2, line R, X, B
= 4, line ratings
= 6, line length
= 8, flow (from bus)
= 10, line losses
= 12, zero sequence line shunts
STATUS(5), line rating to be compared when STATUS(4) is 4:

= 0, all ratings
= 2, RATEB
Real THRESH
= 1, RATEA
= 3, RATEC
Is the difference threshold (input).
Character CFILE*260 Is the name of Saved Case File whose tie lines are to be compared to those
of the working case (input).
Logical SEQFLG(2)
Is an array of two elements returned when APIOPT=0 or 1. The value of

each is as follows:
SEQFLG(1), is true if there is sequence data in the working case.
SEQFLG(2), is true if there is sequence data in the Saved Case in file
CFILE.
Integer IERR

IERR = 1, SID is in error (invalid value or subsystem SID not defined).
IERR = 2, STATUS or THRESH is in error.
IERR = 3, CFILE is in error.
IERR = 4, no ties to compare.
IERR = 6, error opening Saved Case File CFILE.
Integer NERR
Number of error entries in PBUF02 (output).
1-42
PSS/E-29
POWER FLOW APIS

DIFFNW
1.29 DIFFNW
This API is used to provide a tabulation comparing certain power flow data and solution results, as
contained in the working case, with those of a designated Saved Case. The API is invoked by the
use of the statement:
DIFFNW(SID, ALL, APIOPT, STATUS, THRSH, CFILE, SEQFLG, IERR)
or:
BAT_DIFF
STATUS(4)
SID ALL APIOPT STATUS(1) STATUS(2)

THRSH(1) THRSH(2) THRSH(2) CFILE
STATUS(3)
where:
Integer SID

Integer ALL

Integer APIOPT

APIOPT = 1, initialize for comparison.
APIOPT = 2, perform a comparison.
APIOPT = 3, postprocessing of comparison.
Integer STATUS(4)
Is an array of four elements. STATUS has different values/meanings

depending on the value of APIOPT.
If APIOPT = 1, STATUS(1) is the case to leave in the working case.
STATUS(1) = 1, saved case specified in CFILE.
If APIOPT = 1, STATUS(2) is the method used to consider two buses the
same for comparison.
STATUS(2) = 0, bus numbers must be the same.
STATUS(2) = 1, bus names must be the same.
STATUS(2) = 2, bus names and numbers must be the same.
If APIOPT = 2, STATUS(1) is method used for specifying difference
thresholds.
STATUS(1) = 0, threshold in engineering units.
STATUS(1) = 1, threshold as a percent.
PSS/E-29
1-43
POWER FLOW APIS

DIFFNW
If APIOPT = 2, STATUS(2) is the comparison to be performed.

= 1, bus identifiers
= 3, machine status
= 5, generation
= 7, bus shunts
= 9, voltage
= 11, Mbase and Zsorce
= 13, Mbase and Zneg
= 15, negative sequence bus shunts
= 17, branch status
= 19, line shunts
= 21, metered end
= 23, flows (from bus)
= 25, line losses
= 27, zero sequence line shunts
= 29, zero sequence mutuals
= 31, multisection metered end
= 33, line lengths
= 2, bus type codes

= 4, generator MW
= 6, bus loads
= 8, switched shunts
= 10, voltage and angle
= 12, Mbase and Zpos
= 14, Mbase and Zzero
= 16, zero sequence bus shunts
= 18, line R, X, B
= 20, line ratings
= 22, transformers
= 24, flows (from and to)
= 26, zero sequence R, X, B
= 28, grounding codes
= 30, multisection lines
= 32, bus load status
If APIOPT = 2, STATUS(3) is the load characteristic to be compared.

STATUS(3) = 0, total nominal load.
STATUS(3) = 1, constant MVA.
STATUS(3) = 2, constant current.
STATUS(3) = 3, constant admittance.
If APIOPT = 2, STATUS(4) is the line rating set to be compared.
STATUS(4) = 0, all ratings.
STATUS(4) = 1, RATEA.
STATUS(4) = 2, RATEB.
STATUS(4) = 3, RATEC.
If APIOPT = 3, STATUS(1) is the case to leave in the working case.
STATUS(1) = 1, saved case specified in CFILE.
Real THRSH(3)
Is an array of three elements. The value of each is as follows.

THRSH(1), is the difference threshold.
THRSH(2), is the voltage threshold.
THRSH(3), is the angle threshold.
Character CFILE*260 Is the saved case to be compared against the data currently in the working case.
1-44
PSS/E-29
Logical SEQFLG(2)
POWER FLOW APIS

DIFFNW
Is an array of two elements returned when APIOPT = 1. The value of each is

as follows:
SEQFLG(1), is the value of SEQDIN; this is true if there is sequence data
in the working case.
SEQFLG(2), is the value of SEQDIF; this is true is there is sequence data
in the saved case to be compared against.
Integer IERR
PSS/E-29

IERR = 2, STATUS and/or THRSH is in error.
IERR = 3, CFILE is in error.
IERR = 4, error building the case to case translation files.
IERR = 6, error initializing the comparison case.
1-45
POWER FLOW APIS

DSCNAPI
1.30 DSCNAPI
This API executes activity DSCN. The API is invoked by the use of the statement:
DSCNAPI(BUS, IERR, NERR)
or
BAT_DSCN
BUS
where:
Integer BUS
Is the bus number of BUS to be disconnected (input).
Integer IERR

IERR = 1, bus BUS not in working case.
Integer NERR
1-46
PSS/E-29
POWER FLOW APIS

DYN_UNBAL_FAULT
1.31 DYN_UNBAL_FAULT
This API executes activities SEQD and SCMU to calculate the equivalent positive sequence fault
admittance which can be added to the bus shunt at the faulted bus to model a line-to-ground or lineto-line-to-ground fault in dynamic simulation calculations. The API is invoked by the use of the
statement:
DYN_UNBAL_FAULT(OPTIONS, RVAL, IERR, NERR)
where:
Integer OPTIONS(6)
Is an array of six elements specifying options and input values (input). The
first three elements of OPTIONS define options to be used in the construction of the sequence admittance matrices. The remaining entries
define the fault to be applied. The value of each element is as follows.
OPTIONS(1), double precision option.
OPTIONS(1) = 1, use single precision in calculating admittance matrix
terms.
OPTIONS(1) = 2, use double precision in calculating admittance matrix
terms.
OPTIONS(2), dc line and FACTS device option.
OPTIONS(2) = 0, block and ignore.
OPTIONS(2) = 1, convert to constant admittance load.
OPTIONS(3), transformer impedance correction table option.
OPTIONS(3) = 0, do not apply to zero sequence tranformer impedances.
OPTIONS(3) = 1, apply same factor used in the positive sequence to
each tranformers zero sequence impedance.
OPTIONS(4), unbalanced type.
OPTIONS(4) = 0, line-to-ground fault.
OPTIONS(4) = 1, line-to-line or line-to-line-to-ground fault.
OPTIONS(5), bus to be faulted.
OPTIONS(6), faulted (if OPTIONS(4) is 1) or excluded (it OPTIONS(4)
is 2) phase.
OPTIONS(6) = 0, phase A.
OPTIONS(6) = 1, phase B.
OPTIONS(6) = 2, phase C.
Real RVAL(6)
PSS/E-29
Is an array of six elements specifying input values used to define the

fault and containing the results of the fault calculation. The first four elements of RVAL are input value which are dependent on the value
specified for OPTIONS(4). The last two elements of RVAL return the
positive sequence admittance to be used to model the fault in dynamic
simulations. The value of each element is as follows.
1-47
POWER FLOW APIS

DYN_UNBAL_FAULT
RVAL(1), resistance of the complex L-G (if OPTIONS(4) is 1) or L-L

(if OPTIONS(4) is 2) fault impedance in pu.
RVAL(2), reactance of the complex L-G (if OPTIONS(4) is 1) or L-L (if
OPTIONS(4) is 2) fault impedance in pu.
RVAL(3), resistance of the complex L-G fault impedance in pu (if
OPTIONS(4) is 2).
RVAL(4), reactance of the complex L-G fault impedance in pu (if
OPTIONS(4) is 2).
RVAL(5), active component of shunt admittance to ground to model the
fault in MW at unity voltage.
RVAL(6), reactive component of shunt admittance to ground to model
the fault in Mvar at unity voltage.
Integer IERR

IERR => 0, no error occurred.
IERR => 1, no case in memory.
IERR => 2, sequence data not in case.
IERR => 3, invalid OPTIONS value.
IERR => 7, invalid unbalance type.
IERR => 8, bus not found.
IERR => 9, invalid phase value.
Integer NERR
1-48
PSS/E-29
POWER FLOW APIS

ECDINW
1.32 ECDINW
This API is used to place machines in a specified subsystem on or off line to satisfy a given subsystem minimum capacity. The in-service machines in the subsystem are then dispatched on the
basis of incremental cost to meet a specified total subsystem generation. The API is invoked by the
ECDINW(SID, ALL, APIOPT, GFILE, PROFILE, DESPWR, CAPCTY, IERR)
or:
BAT_ECDI
SID
ALL
APIOPT
GFILE
PROFILE
DESPWR
CAPCTY
where:
Integer SID

Integer ALL

Integer APIOPT

APIOPT = 1, initialize for dispatch.
APIOPT = 2, perform unit commitment.
Character GFILE*260 Is the economic dispatch data file.

Integer PROFILE
Is the initial commitment option.

PROFILE = 0, start from current commitment profile.
PROFILE = 1, new commitment profile.
Real DESPWR
Is the desired load.
Real CAPCTY
Is the desired minimum capacity of units being dispatched.
Integer IERR

IERR = 3, GFILE is in error.
IERR = 4, PROFILE is in error.
IERR = 5, reenter DESPWR and CAPCTY with new values.
IERR = 6, no dispatchable machines in subsystem.
PSS/E-29
1-49
POWER FLOW APIS

ECHOAPI
1.33 ECHOAPI
This API executes activity ECHO. The API is invoked by the use of the statement:
ECHOAPI(IDVFILE, IERR, NERR)
or
BAT_ECHO
IDVFILE
where:
Character IDVFILE*260 Is the name of Response File to be constructed (blank to disable) (input).
Integer IERR

IERR = 1, error opening file IDVFILE.
Integer NERR
1-50
PSS/E-29
POWER FLOW APIS

EEQVNW
1.34 EEQVNW
This API is used to construct an electrical equivalent of a subsystem of the network contained in the
EEQVNW(SID, ALL, STATUS, DVAL, IERR)
or:
BAT_EEQV
STATUS(5)
SID ALL STATUS(1) STATUS(2)

STATUS(6) DVAL(1) DVAL(2)
STATUS(3)
STATUS(4)
where:
Integer SID
Is a valid bus subsystem ID. Valid subsystem IDs range from 0 to 3. A bus subsystem must have been previously defined (input).
Integer ALL

Integer STATUS(6)
Is an array of six elements. They are used to control equivalencing options. A

value of 0 means the option is not enabled. A value of 1 means the option is
enabled. They are as follows.
STATUS(1), retain area boundary buses.
STATUS(2), retain zone boundary buses.
STATUS(3), suppress equivalencing of phase shifters.
STATUS(4), retain controlled buses.
STATUS(5), retain existing branches.
STATUS(6), net load and shunt at type two buses.
Real DVAL(2)
Is an array of two elements. They are as follows.

DVAL(1), minimum generations for maintaining generator buses.
DVAL(2), branch threshold tolerance.
Integer IERR

PSS/E-29
1-51
POWER FLOW APIS

EQRDNW
1.35 EQRDNW
This API is used to equivalence radial and, optionally, "two point" type one buses in specified subsystems of the working case. The API is invoked by the use of the statement:
EQRDNW(SID, ALL, STATUS, IERR)
or:
BAT_EQRD
STATUS(5)

STATUS(6) STATUS(7) STATUS(8)
STATUS(3)
STATUS(4)
where:
Integer SID
Integer ALL

Integer STATUS(8)
Is an array of eight elements. They are used to control equivalencing options.

A value of 0 means the option is not enabled. A value of 1 means the option is
STATUS(1), equivalence radial buses only.
STATUS(2), suppress equivalencing of transformers.
STATUS(3), suppress equivalencing of zero impedance lines.
STATUS(4), suppress equivalencing of controlled buses.
STATUS(5), suppress equivalencing of mutually coupled branches.
STATUS(6), suppress equivalencing of area boundary buses.
STATUS(7), suppress equivalencing of zone boundary buses.
STATUS(8), apply transformer impedance correction to zero sequence
lines.
Integer IERR

1-52
PSS/E-29
POWER FLOW APIS

EXAMNW
1.36 EXAMNW
This API is used to provide a tabulation of all power flow data pertaining to a selected bus. The API
is invoked by the use of the statement:
EXAMNW(SID, ALL, IERR)
or:
BAT_EXAM
SID
ALL
where:
Integer SID
Is a valid subsystem ID. Valid subsystem IDs range from 0-3. A subsystem
Integer ALL

Integer IERR

PSS/E-29
1-53
POWER FLOW APIS

EXTRNW
1.37 EXTRNW
This API is used to purge specified buses and all branches connected to them from the working case.
EXTRNW(SID, ALL, STATUS, IERR)
or:
BAT_EXTR
SID
ALL
STATUS(1)
STATUS(2)
where:
Integer SID
Integer ALL

Integer STATUS(2)
Is an array of two elements. They are used to control purging options. A value
of 0 means the option is not enabled. A value of 1 means the option is enabled.
They are as follows.
STATUS(1), remove generator entries for out of service plants.
STATUS(2), change codes of boundary buses.
Integer IERR

1-54
PSS/E-29
POWER FLOW APIS

FACTAPI
1.38 FACTAPI
This API executes activity FACT. The API is invoked by the use of the statement:
FACTAPI(IERR, NERR)
or
BAT_FACT
where:
Integer IERR

IERR = 2, generators are not "converted".
Integer NERR
PSS/E-29
1-55
POWER FLOW APIS

FDNSAPI
1.39 FDNSAPI
This API executes activity FDNS. This API uses the default element specification as described in
FDNSAPI(OPTIONS, IERR, NERR)
or
BAT_FDNS
OPTIONS(5)
OPTIONS(1) OPTIONS(2) OPTIONS(3)

OPTIONS(4)
where:
Integer OPTIONS(8)
Is an array of eight elements specifying solution options (input). The

interchange.
interchange.
OPTIONS(6), flat start flag.
OPTIONS(6) = 0, do not flat start.
OPTIONS(6) = 1, flat start.
OPTIONS(7), var limit flag.
OPTIONS(7) = 0, apply var limits immediately.
1-56
PSS/E-29
POWER FLOW APIS

FDNSAPI
OPTIONS(7) = >0, apply var limits on iteration n (or sooner if mismatch

gets small).
OPTIONS(7) = -1, ignore var limits.
Integer IERR

Integer NERR

PSS/E-29
1-57
POWER FLOW APIS

FILE_OVERWRITE_API
1.40 FILE_OVERWRITE_API
This API is used to set the value of the file overwrite option setting to either "ask first" or "overwrite". The API is invoked by the use of the statement:
FILE_OVERWRITE_API(IVAL, IOCODE, IERR, NERR)
or
BAT_FILE_OVERWRITE
IVAL
where:
Integer IVAL
Is the value of the option setting (input it IOCODE is 0 or BAT_command,

IVAL = 0, ask first.
IVAL = 1, overwrite.
Integer IOCODE

Integer IERR

Integer NERR
1-58
PSS/E-29
POWER FLOW APIS

FINDAPI
1.41 FINDAPI
This API executes activity FIND. The API is invoked by the use of the statement:
FINDAPI(NAME, BSKV, IERR, NERR)
or
BAT_FIND
NAME, BSKV
where:
Character NAME
Is the bus name (up to 16 characters) (input).
Character BSKV
Is the bus base voltage (up to 12 characters) (input).
Integer IERR

IERR = 2, error decoding BSKV.
Integer NERR
PSS/E-29
1-59
POWER FLOW APIS

FLATAPI
1.42 FLATAPI
This API executes activity FLAT. This API uses the default element specification as described in
FLATAPI(OPTIONS, VALUES, IERR, NERR)
or
BAT_FLAT
VALUES(1)
OPTIONS(1)
VALUES(2)
OPTIONS(2)
OPTIONS(3)
OPTIONS(4)
where:
Integer OPTIONS(4)
Is an array of four elements specifying boundary condition options (input).

The values are as follows:
OPTIONS(1), flat option.
OPTIONS(1) = 0, only change voltages (activity FLAT).
OPTIONS(1) = 1, set classical fault analysis conditions (activity FLAT,CL).
OPTIONS(1) = 2, set conditions in preparation for IEC standard 909 calculations (activity FLAT,IEC).
OPTIONS(2), tap ratio treatment flag (ignored if OPTIONS(1) = 0).
OPTIONS(2) = 0, leave tap ratios unchanged.
OPTIONS(2) = 1, set tap ratios to 1.0.
OPTIONS(3), charging treatment flag (ignored if OPTIONS(1) = 0).
OPTIONS(3) = 0, leave charging unchanged.
OPTIONS(3) = 1, set charging to 0.0.
OPTIONS(4), shunt treatment flag (ignored if OPTIONS(1) = 0).
OPTIONS(4) = 0, leave shunts unchanged.
OPTIONS(4) = 1, set shunts to 0.0 in the positive sequence.
OPTIONS(4) = 2, set shunts to 0.0 in all sequence networks.
Real VALUES(2)
Is an array of two elements specifying boundary condition values (ignored

unless OPTIONS(1) = 2) (input). The values are as follows:
VALUES(1), voltage magnitude for all buses, or 0.0 to use present voltage
magnitudes.
VALUES(2), generator power factor, or 0.0 to leave generator Mvar
unchanged.
Integer IERR

IERR = 2, invalid VALUES value.
Integer NERR
1-60
PSS/E-29
POWER FLOW APIS

FNSLAPI
1.43 FNSLAPI
This API executes activity FNSL. This API uses the default element specification as described in
FNSLAPI(OPTIONS, IERR, NERR)
or
BAT_FNSL
OPTIONS(5)

OPTIONS(4)
where:
Integer OPTIONS(8)
Is an array of eight elements specifying solution options (input). The

interchange.
interchange.
PSS/E-29
1-61
POWER FLOW APIS

FNSLAPI

gets small).
Integer IERR

Integer NERR
1-62
PSS/E-29
POWER FLOW APIS

GCAPNW
1.44 GCAPNW
This API is used read a data file containing capability curve data and prints a report of machine
loading and limit data. Optionally, machine reactive power limits in the working case may be
updated. The API is invoked by the use of the statement:
GCAPNW(SID, ALL, OPT, GFILE, IERR)
or:
BAT_GCAP
SID
ALL
OPT
GFILE
where:
Integer SID

Integer ALL

Integer OPT
Is the update var limits option.

OPT = 0, leave var limits alone.
OPT = 1, update var limits in the working case.
Character GFILE*260 Is the capability curve data file.

Integer IERR
PSS/E-29

IERR = 2, OPT is in error.
IERR = 3, GFILE is in error.
1-63
POWER FLOW APIS

GDIFAPI
1.45 GDIFAPI
This API calculates differences between the working case and a designated Saved Case. Results
may be programmatically accessed via the "fetch" routines DIFTXT, DIFBUS, DIFBRN, DIF3WN,
DIF2DC, DIFMDC and DIFFCT.
Usage is:
call to GDIFAPI with APIOPT = 0;

multiple calls to "fetch" routines;
optionally, repeat of above steps for different Saved Case and/or subsystem;
final call to GDIFAPI with APIOPT = 1.

GDIFAPI(SID, ALL, APIOPT, NAMARG, FILARG, IERR, NERR)
or:
BAT_GCAP
SID
ALL
APIOPT
NAMARG
FILARG
where:
Integer SID
Is a valid subsystem ID. Valid subsystem IDs range from 0 to 3. A subsystem must have been previously defined (input).
Integer ALL
Is the "all" buses or selected subsystem flag for calculating differences (input).
ALL = 0, only buses in subsystem "SID".
ALL = 1, all buses in the working case.
Integer APIOPT
Is the mode of operation of GDIFAPI (input).

APIOPT = 0, do difference calculations and fill arrays used by fetch
routines.
APIOPT = 1, deallocate arrays used by fetch routines.
Integer NAMARG
Is the flag indicating how to match up buses in the two cases (input).
NAMARG = 0, by bus number only.
NAMARG = 1, by extended bus name only.
NAMARG = 2, by both number and name.
Character FILARG*260Is the name of Saved Case File to be compared to the working case (input).
Integer IERR

IERR = 2, invalid APIOPT value.
IERR = 3, invalid NUMARG value.
IERR = 4, FILARG contains all blanks.
IERR = 5, set up error from subroutine DIFINI.
Integer NERR
1-64
PSS/E-29
POWER FLOW APIS

GENSNW
1.46 GENSNW
This API is used to tabulate the loading and voltage conditions at plant buses. The API is invoked
by the use of the statement:
GENSNW(SID, ALL, OPT, VREV, IERR)
or:
BAT_GENS
SID
ALL
OPT
VREV
where:
Integer SID

Integer ALL

Integer OPT
Is type of plant to tabulate.

OPT = 1, tabulate var limited plants with unequal var limits.
OPT = 2, tabulate all var limited plants.
OPT = 3, tabulate online plants.
OPT = 4, tabulate all plants
Integer VREV
Is used to change voltage output units from the default units to the alternate
units.
VREV = 0, use default voltage units.
VREV = 1, use alternate voltage units.
Integer IERR

IERR = 2, OPT or VREV is in error.
PSS/E-29
1-65
POWER FLOW APIS

GEOLNW
1.47 GEOLNW
This API is used to tabulate the loading and voltage conditions at the generator terminals for online
machines at type two and three buses in the working case. The API is invoked by the use of the
statement:
GEOLNW(SID, ALL, OPT, IERR)
or:
BAT_GEOL
SID
ALL
OPT
where:
Integer SID

Integer ALL

Integer OPT
Is used to restrict the type of machine to tabulate.

OPT = 1, tabulate overloaded machines only.
OPT = 2, tabulate all machines.
Integer IERR

1-66
PSS/E-29
POWER FLOW APIS

GNETNW
1.48 GNETNW
This API is used to change the in-service generation to negative MVA load at all type two and three
buses within the subsystem specified by the user. The API is invoked by use of the statement:
GNETNW(SID, ALL, IERR)
or:
BAT_GNET
SID
ALL
where:
Integer SID

Integer ALL

Integer IERR

PSS/E-29
1-67
POWER FLOW APIS

GSDFLT
1.49 GSDFLT
This subroutine returns the default solution options for the Gauss-Seidel solution activities SOLV
and MSLV. The API is invoked by the use of the statement:
GSDFLT(TAPOPT, INTOPT, DCOPT, SWSOPT)
where:
Integer TAPOPT
Is the tap adjustment flag (output).

TAPOPT = 0, disabled.
TAPOPT = 1, enabled.
Integer INTOPT
Is the area interchange adjustment flag (output).

INTOPT = 0, disabled.
INTOPT = 1, enabled using tie line flows only in calculating area
interchange.
INTOPT = 2, enabled using tie line flows and loads in calculating area
interchange.
Integer DCOPT
Is the dc tap adjustment flag (output).

DCOPT = 0, disabled.
DCOPT = 1, enabled.
Integer SWSOPT
Is the switched shunt adjustment flag (output).

SWSOPT = 0, disabled.
SWSOPT = 1, enabled.
1-68
PSS/E-29
POWER FLOW APIS

IMPCAPI
1.50 IMPCAPI
This API executes activity IMPC. The API is invoked by the use of the statement:
IMPCAPI(EVENT, DFXFILE, ATCFILE, IERR, NERR)
or
BAT_IMPC
EVENT, DFXFILE, ATCFILE
where:
Integer EVENT
Is the transaction event numeric identifier (input).
Character ATCFILE*260 Is the name of ATC update input file; blank for none (input).
Integer IERR

IERR = 2, invalid EVENT value.
IERR = 3, no transactions defined.
IERR = 4, no DFAX input file specified.
IERR = 5, subroutine INPROC error.
Integer NERR
PSS/E-29
1-69
POWER FLOW APIS

INLFAPI
1.51 INLFAPI
This API executes activity INLF. This API uses the default element specification as described in
INLFAPI(OPTIONS, FILE, IERR, NERR)
or
BAT_INLF
OPTIONS(5)

OPTIONS(6) OPTIONS(7) FILE
OPTIONS(4)
where:
Integer OPTIONS(7)

OPTIONS(1), solution type.
OPTIONS(1) = 0, inertial.
OPTIONS(1) = 1, governor response.
OPTIONS(2) = -1, solution type default (inertial => disabled; governor =>
stepping).
enabled).
enabled).
OPTIONS(5) = -1, solution type default (inertial => enabled; governor =>
enabled).
1-70
PSS/E-29
POWER FLOW APIS

INLFAPI

gets small).
OPTIONS(7), missing active power limits flag (only used in governor
response load flow).
OPTIONS(7) = 0, pre-PSS/E-29 approach (0.0 to 1.0 pu for machines with
no Economic Dispatch Data File read; working case values for machines
with PMAX defaulted on ECDI data record).
OPTIONS(7) = 1, 0.0 to 1.0 pu for both categories of machines.
OPTIONS(7) = 2, working case values for both categories of machines.
Character FILE*260
Is the name of Inertia and Governor Response Data file; blank for none
(input).
Integer IERR

IERR = 2, error opening input file FILE.
Integer NERR
PSS/E-29
1-71
POWER FLOW APIS

INTANW
1.52 INTANW
This API is used to summarize tie flows between an interchange area and all other areas in the
INTANW(SID, ALL, IERR)
or:
BAT_INTA
SID
ALL
where:
Integer SID
Is a valid area subsystem ID. Valid subsystem IDs range from 0 to 3. An area
subsystem must have been previously defined (input).
Integer ALL
Is the "all" areas or selected area subsystem flag (input).

Integer IERR

1-72
PSS/E-29
POWER FLOW APIS

INTZNW
1.53 INTZNW
This API is used to summarize tie flows between each zone and all other zones in the working case.
INTZNW(SID, ALL, IERR)
or:
BAT_INTZ
SID
ALL
where:
Integer SID
Is a valid zone subsystem ID. Valid subsystem IDs range from 0 to 3. A zone
Integer ALL
Is the "all" zones or selected zone subsystem flag (input).

ALL = 1, process all zones.
ALL = 0, process only selected zones.
Integer IERR

PSS/E-29
1-73
POWER FLOW APIS

JOINAPI/JOINNW
1.54 JOINAPI/JOINNW
JOINAPI(RBUS, JBUS, STATUS, NID, IDTRNS, IERR, NERR)
or
JOINNW(RBUS, JBUS, STATUS, IERR)
or
BAT_JOIN
RBUS
JBUS
STATUS
where:
Integer RBUS
Is the retained bus (input).
Integer JBUS
Is the eliminated bus (input).
Integer STATUS
Is the line shunt option (input)

STATUS(1) = 0, ignore line shunts of deleted branches.
STATUS(1) = 1, add line shunts of deleted branches to shunt of retained
bus.
Integer NID
Is the number of elements in IDTRNS array (input).
Character IDTRNS*18 Is the ID translation array of NID entries (output). Contains information on
identifier changes of elements originally connected to bus JBUS. IDTRNS
contents:
Columns
Content
LD for load.
BR for non-transformer branch.
1-2
MC for machine.
T2 for two-winding transformer.
T3 for three-winding transformer.
For BR and T2 records, bus number at
the other end of the branch.
3-8
1-74
For T3 records, bus number of one of

the other buses connected by the
transformer.
9-14
For T3 records, bus number of the

other bus connected by the
transformer.
15-16
Old identifier.
17-18
New identifier.
PSS/E-29
POWER FLOW APIS

JOINAPI/JOINNW
Integer IERR

IERR = 1, invalid STATUS value.
IERR = 2, RBUS or JBUS not in working case.
IERR = 3, invalid NID value.
IERR = 4, IDTRNS not big enough.
IERR = 5, JOIN processing error.
Integer NERR
PSS/E-29
1-75
POWER FLOW APIS

LAMPNW
1.55 LAMPNW
This API is used to print power flow and amp data in a wide format, greater than 80 columns. The
LAMPNW(SID, ALL, IERR)
or:
BAT_LAMP
SID
ALL
where:
Integer SID
Integer ALL

Integer IERR

1-76
PSS/E-29
POWER FLOW APIS

LINE_SHUNT_REPORTING_API
1.56 LINE_SHUNT_REPORTING_API
This API is used to set the value of the line shunt reporting option setting to either "no" or "yes".
LINE_SHUNT_REPORTING_API(IVAL, IOCODE, IERR, NERR)
or
BAT_LINE_SHUNT_REPORTING
IVAL
where:
Integer IVAL

IVAL = 0, no special reporting of line shunts in POUT, LOUT and LAMP.
IVAL = 1, include special reporting of line shunts in POUT, LOUT and
LAMP.
Integer IOCODE

Integer IERR

Integer NERR
PSS/E-29
1-77
POWER FLOW APIS

LINES_PER_PAGE_API
1.57 LINES_PER_PAGE_API
This API is used to set the values of the four output device page length limits option settings. The
CALL LINES_PER_PAGE_API(IVAL, DEVNAM, IOCODE, IERR, NERR)
or
BAT_LINES_PER_PAGE
IVAL
where:
Integer IVAL
Is an array of four elements containing the value of the option setting (input
it IOCODE is 0 or BAT_command, output if IOCODE is 1).
IVAL(1), lines per page for disk files.
IVAL(2), lines per page for the "report" window.
IVAL(3), lines per page for the first primary hard copy output device.
IVAL(4), lines per page for the second primary hard copy output device.
Character DEVNAM*40 Is an array of four elements set to the device names of the four output
devices (output if IOCODE is 1, not used if IOCODE is 0 or BAT_
command).
DEVNAM(1), FILE OUTPUT.
DEVNAM(2), CRT TERMINAL.
DEVNAM(3), name of first primary hard copy output device.
DEVNAM(4), name of second primary hard copy output device.
Integer IOCODE

IOCODE = 0, set the option settings to the values specified in IVAL.
IOCODE = 1, return the current values of the option settings in IVAL.
Integer IERR

IERR = 1, negative IVAL value.
Integer NERR
1-78
PSS/E-29
POWER FLOW APIS

LISTNW
1.58 LISTNW
This API is used to tabulate the power flow working case in a form suitable for problem data documentation. The API is invoked by the use of the statement:
LISTNW(SID, ALL, OPT, VREV, IERR)
or:
BAT_LIST
SID
ALL
OPT
VREV
where:
Integer SID

Integer ALL

Integer OPT
Is type of power flow data to tabulate.

= 1, case summary
= 3, switched shunt data
= 5, generator unit data
= 7, branch data (double entry)
= 9, line shunt data
= 11, area interchange data
= 13, full listing (double entry)
= 15, multisection line data
= 17, interarea transfer data
= 19, owner data
= 21, two-winding transformer tap and
control data
=23, three-winding transformer
winding data
= 2, bus data
= 4, plant data
= 6, branch data (single entry)
= 8, two-winding transformer
impedance data
= 10, dc line data
= 12, full listing (single entry)
= 14, impedance correct data
= 16, zone data
= 18, load data
= 20, FACTS control device
data
= 22, three-winding transformer
impedance data
control data
Integer VREV
units.
Integer IERR

PSS/E-29
1-79
POWER FLOW APIS

LLRFAPI
1.59 LLRFAPI
This API executes activity LLRF. It must first be called once with APIOPT set to 1, then once for
each priority level whose adjustment method is to be changed with APIOPT set to 2, and finally
once with APIOPT set to 3. The API is invoked by the use of the statement:
CALL LLRFAPI(APIOPT, OPTIONS, RVAL, DFXFILE, IERR, NERR)
or
BAT_LLRF
APIOPT
OPTIONS(1)
OPTIONS(2)
RVAL
DFXFILE
where:
Integer APIOPT
Is the mode of operation of LLRFAPI (input).

APTOPT = 1, initialize.
APTOPT = 2, specify a priority level and the adjustment method to be
applied; must be called once for each priority level, adjustment method
pair to be specified.
APTOPT = 3, specify a line loading relief function, perform the required
calculations, report results, and terminate.
Integer OPTIONS(2)
Is an array of two elements specifying options and input values to be used

in the current calculation phase of LLRFAPI; ignored when APIOPT is 1
(input).
When APIOPT is 2, the elements of OPTIONS define a priority level and
the adjustment method to be used in curtailing or restoring transactions.
OPTIONS(1), priority level.
OPTIONS(2), adjustment method.
OPTIONS(2) = 0, first in, last out (FILO).
OPTIONS(2) = 1, decreasing order of distribution factor magnitude (DFORDER).
OPTIONS(2) = 2, distribution factor pro rata (DF-PRO RATA).
OPTIONS(2) = 3, pro rata base on the product of distribution factor and
transaction schedule (DF-SCHED-PRO RATA).
When APIOPT is 3, the first element of OPTIONS defines the line loading
relief function to be performed. For the "curtail transactions" and "restore
transactions" functions, the second element of OPTIONS defines the monitored element to be used as the transaction adjustment target.
OPTIONS(1), line loading relief function.
OPTIONS(1) = 0, curtail transactions.
OPTIONS(1) = 1, restore transactions.
OPTIONS(1) = 2, report distribution factor matrix.
OPTIONS(2), monitored element list index.
1-80
PSS/E-29
POWER FLOW APIS

LLRFAPI
Real RVAL
When APIOPT is 1, RVAL is the distribution factor tolerance used to

preclude those transactions with negligible effect on the target monitored element from the transaction adjustment functions. When APIOPT
is 3, RVAL is the target element adjustment MW (input).
Character DFXFILE*260 Is the name of Distribution Factor Data input file when APIOPT is 1
(input).
Integer IERR

IERR = 3, invalid APIOPT 1 call (already made; need APIOPT 2 or 3
call).
IERR = 4, invalid APIOPT 2 or 3 call (no APIOPT 1 call).
IERR = 6, no transactions defined.
Integer NERR
PSS/E-29
1-81
POWER FLOW APIS

LOUTNW
1.60 LOUTNW
This API is used to print power flow data in a wide format, greater than 80 columns. The API is
LOUTNW(SID, ALL, IERR)
or:
BAT_LOUT
SID
ALL
where:
Integer SID
Integer ALL

Integer IERR

1-82
PSS/E-29
POWER FLOW APIS

LTAPAPI
1.61 LTAPAPI
This API is used to tap a line. The API is invoked by the use of the statement:
LTAPAPI(FRMBUS, TOBUS, CKT, FRACTION, NEWNUM, NEWNAM, NEWKV, IERR,
NERR)
or
BAT_LTAP
NEWKV
FRMBUS
TOBUS
CKT
FRACTION
NEWNUM
NEWNAM
where:
Integer FRMBUS
Is one of the buses connected by the branch to be tapped (input).
Integer TOBUS
Is the other bus connected by the branch to be tapped (input).
Character CKT*2
Is the circuit identifier of the branch to be tapped (input).
Real FRACTION
New bus location relative to bus FRMBUS in per unit of total line length
(input).
Integer NEWNUM
Is the number to be assigned to the new bus (input).
Character NEWNAM*8 Is the name to be assigned to the new bus (input).

Real NEWKV
Is the base voltage to be assigned to the new bus (input).
Integer IERR

IERR = 1, FRMBUS or TOBUS not in working case.
IERR = 2, circuit CKT connecting FRMBUS and TOBUS not in working
case.
IERR = 3, branch is a transformer.
IERR = 4, invalid FRACTION value.
IERR = 5, invalid NEWNUM value.
IERR = 6, bus NEWNUM already in working case.
IERR = 7, invalid NEWKV value.
IERR = 8, bus, branch, or branch ownership tables full.
Integer NERR
PSS/E-29
1-83
POWER FLOW APIS

MATRIX_GROWTH_FACTOR_API
1.62 MATRIX_GROWTH_FACTOR_API
This API is used to set the value of the matrix growth factor option setting. The API is invoked by
CALL MATRIX_GROWTH_FACTOR_API(RVAL, IOCODE, IERR, NERR)
or
BAT_MATRIX_GROWTH_FACTOR
RVAL
where:
Integer RVAL

Integer IOCODE

Integer IERR

Integer NERR
1-84
PSS/E-29
POWER FLOW APIS

MBID2DC
1.63 MBID2DC
This API changes the dc line number of the specified two-terminal dc line. The API is invoked by
MBID2DC(DC, DCNEW, IERR, NERR)
or
BAT_MBID2DC
DC
DCNEW
where:
Integer DC
Is the number of the two-terminal dc line whose dc line number is to be

changed (input).
Integer DCNEW
Is the new number to be assigned to the two-terminal dc line (input).
Integer IERR

IERR = 1, DC is invalid dc line number.
IERR = 2, dc line DC not in working case.
IERR = 3, DCNEW is invalid dc line number.
IERR = 4, dc line DCNEW already in working case.
IERR = 5, two-terminal dc line table full.
Integer NERR
PSS/E-29
1-85
POWER FLOW APIS

MBID3WND
1.64 MBID3WND
This API changes the identifier of the specified three-winding transformer. The API is invoked by
MBID3WND(FRMBUS, TOBUS1, TOBUS2, ID, IDNEW, IERR, NERR)
or
BAT_MBID3WND
FRMBUS
TOBUS1
TOBUS2
ID
IDNEW
where:
Integer FRMBUS
Is one of the buses connected by the three-winding transformer (input).
Integer TOBUS1
Is another bus connected by the three-winding transformer (input).
Integer TOBUS2
Is the other bus connected by the three-winding transformer (input).
Character ID*2
Is the present circuit identifier of the three-winding transformer whose

identifier is to be changed (input).
Character IDNEW*2
Is the new identifier to be assigned to the three-winding transformer

(input).
Integer IERR

IERR = 1, FRMBUS, TOBUS1 or TOBUS2 not in working case.
IERR = 2, circuit ID connecting FRMBUS, TOBUS1 and TOBUS2 not in
working case.
IERR = 3, circuit IDNEW already assigned to a three-winding transformer
connecting FRMBUS, TOBUS1 and TOBUS2.
IERR = 4, IDNEW is invalid identifier.
Integer NERR
1-86
PSS/E-29
POWER FLOW APIS

MBIDATRN
1.65 MBIDATRN
This API changes the identifier of the specified inter-area transfer. The API is invoked by the use
of the statement:
MBIDATRN(FRMAREA, TOAREA, ID, IDNEW, IERR, NERR)
or
BAT_MBIDATRN
FRMAREA
TOAREA
ID
IDNEW
where:
Integer FRMAREA
Is one of the areas involved in the transfer (input).
Integer TOAREA
Is the other area involved in the transfer (input).
Character ID*1
Is the present inter-area transfer identifier (input).
Character IDNEW*1
Is the new identifier to be assigned to the inter-area transfer (input).
Integer IERR

IERR = 1, FRMAREA or TOAREA is invalid area number.
IERR = 2, inter-area transfer ID between areas FRMAREA and TOAREA
not in working case.
IERR = 3, identifier IDNEW already assigned to an inter-area transfer
between areas FRMAREA and TOAREA.
IERR = 4, IDNEW is an invalid identifier.
Integer NERR
PSS/E-29
1-87
POWER FLOW APIS

MBIDBRN
1.66 MBIDBRN
This API changes the identifier of the specified non-transformer branch or two-winding transformer. The API is invoked by the use of the statement:
MBIDBRN(FRMBUS, TOBUS, ID, IDNEW, IERR, NERR)
or
BAT_MBIDBRN
FRMBUS
TOBUS
ID
IDNEW
where:
Integer FRMBUS
Is one of the buses connected by the branch (input).
Integer TOBUS
Is the other bus connected by the branch (input).
Character ID*2
Is the present circuit identifier of the branch whose identifier is to be

changed (input).
Character IDNEW*2
Is the new identifier to be assigned to the branch (input).
Integer IERR

IERR = 2, circuit ID connecting FRMBUS and TOBUS not in working
case.
IERR = 3, circuit IDNEW already assigned to a branch connecting
FRMBUS and TOBUS.
Integer NERR
1-88
PSS/E-29
POWER FLOW APIS

MBIDFACTS
1.67 MBIDFACTS
This API changes the FACTS device number of the specified FACTS device. The API is invoked
MBIDFACTS(FD, FDNEW, IERR, NERR)
or
BAT_MBIDFACTS
FD
FDNEW
where:
Integer FD
Is the number of the FACTS device whose FACTS device number is to be

changed (input).
Integer FDNEW
Is the new number to be assigned to the FACTS device (input).
Integer IERR

IERR = 1, FD is invalid FACTS device number.
IERR = 2, FACTS device FD not in working case.
IERR = 3, FDNEW is invalid FACTS device number.
IERR = 4, FACTS device FDNEW already in working case.
IERR = 5, FACTS device table full.
Integer NERR
PSS/E-29
1-89
POWER FLOW APIS

MBIDLOAD
1.68 MBIDLOAD
This API changes the identifier of the specified load. The API is invoked by the use of the statement:
MBIDLOAD(FRMBUS, ID, IDNEW, IERR,NERR)
or
BAT_MBIDLOAD
FRMBUS
ID
IDNEW
where:
Integer FRMBUS
Is the bus to which load "ID" is connected (input).
Character ID*2
Is the present load identifier of the load whose identifier is to be changed

(input).
Character IDNEW*2
Is the new identifier to be assigned to the load (input).
Integer IERR

IERR = 1, FRMBUS not in working case.
IERR = 2, load ID at bus FRMBUS not in working case.
IERR = 3, load IDNEW already assigned to a load at bus FRMBUS.
IERR = 4, IDNEW is blank.
Integer NERR
1-90
PSS/E-29
POWER FLOW APIS

MBIDMAC
1.69 MBIDMAC
This API changes the identifier of the specified machine. The API is invoked by the use of the
statement:
MBIDMAC(FRMBUS, ID, IDNEW, IERR, NERR)
or
BAT_MBIDMAC
FRMBUS
ID
IDNEW
where:
Integer FRMBUS
Is the bus to which machine "ID" is connected (input).
Character ID*2
Is the present machine identifier of the machine whose identifier is to be

changed (input).
Character IDNEW*2
Is the new identifier to be assigned to the machine (input).
Integer IERR

IERR = 2, machine ID at bus FRMBUS not in working case.
IERR = 3, machine IDNEW already assigned to a machine at bus
FRMBUS.
Integer NERR
PSS/E-29
1-91
POWER FLOW APIS

MBIDMDC
1.70 MBIDMDC
This API changes the dc line number of the specified multi-terminal dc line. The API is invoked by
MBIDMDC(DC, DCNEW, IERR, NERR)
or
BAT_MBIDMDC
DC
DCNEW
where:
Integer DC
Is the number of the multi-terminal dc line whose dc line number is to be

changed (input).
Integer DCNEW
Is the new number to be assigned to the multi-terminal dc line (input).
Integer IERR

IERR = 1, DC is invalid dc line number.
IERR = 3, DCNEW is invalid dc line number.
IERR = 4, dc line DCNEW already in working case.
IERR = 5, multi-terminal dc line table full.
Integer NERR
1-92
PSS/E-29
POWER FLOW APIS

MBIDMSL
1.71 MBIDMSL
This API changes the identifier of the specified multi-section line. The API is invoked by the use
of the statement:
MBIDMSL(FRMBUS, TOBUS, ID, IDNEW, IERR, NERR)
or
BAT_MBIDMSL
FRMBUS
TOBUS
ID
IDNEW
where:
Integer FRMBUS
Is one of the buses connected by the multi-section line (input).
Integer TOBUS
Is the other bus connected by the multi-section line (input).
Character ID*2
Is the present multi-section identifier of the multi-section line whose identifier is to be changed (input).
Character IDNEW*2
Is the new identifier to be assigned to the multi-section line (input).
Integer IERR

IERR = 2, Multi-section line ID connecting FRMBUS and TOBUS not in
working case.
IERR = 3, Multi-section line IDNEW already assigned to a multi-section
line connecting FRMBUS and TOBUS.
Integer NERR
PSS/E-29
1-93
POWER FLOW APIS

MBIDVSC
1.72 MBIDVSC
This API changes the VSC dc line name of the specified VSC dc line. The API is invoked by the
CALL MBIDVSC(NAME, NAMNEW, IERR, NERR)
or
BAT_MBIDVSC
NAME
NAMNEW
where:
Character NAME*8
Is the name of the VSC dc line whose VSC dc line name is to be changed
(input).
Character NAMNEW*8Is the new name to be assigned to the VSC dc line (input).
Integer IERR

IERR = 1, VSC dc line NAME not in working case.
IERR = 2, VSC dc line NEWNAM already in working case.
IERR = 3, NEWNAM must be non-blank.
Integer NERR
1-94
PSS/E-29
POWER FLOW APIS

MCREAPI
1.73 MCREAPI
This API executes activity MCRE. The API is invoked by the use of the statement:
MCREAPI(STATUS, FILE, IERR, NERR)
or
BAT_MCRE
STATUS(1)
STATUS(2)
FILE
where:
Integer STATUS(2)
Is an array of two elements specifying MCRE options (input)

STATUS(1), new machine status option.
STATUS(1) = 0, set from STAT field on input record.
STATUS(1) = 1, set from status of other machines at the bus.
STATUS(2), option for treatment of machines with no data record
specified and other machines at the bus with record specified.
STATUS(2) = 0, place out-of-service.
STATUS(2) = 1, delete.
Character FILE*260
Is the filename of Machine Impedance Data Input File (input).
Integer IERR

IERR = 3, generators are converted.
Integer NERR
PSS/E-29
1-95
POWER FLOW APIS

MODRNW
1.74 MODRNW
This API is used to uniformly increase or decrease the line resistances of in-service nontransformer
branches. The API is invoked by the use of the statement:
MODRNW(SID, ALL, APIOPT, IRAT, RLOAD, FMAX, NCHNG, IERR)
or:
BAT_MODR
SID
ALL
APIOPT
IRAT
RLOAD
FMAX
where:
Integer SID
Integer ALL

Integer APIOPT

APIOPT = 1, initialize system for line resistance modification.
APIOPT = 2, modify line resistances.
APIOPT = 3, postprocessing of line resistance modification.
Integer IRAT
Is the rating set on which the present values of branch resistances are based.
IRAT = 1, RATEA.
IRAT = 2, RATEB.
IRAT = 3, RATEC.
Real RLOAD
Is the base line loading in percent. 0.0001 <= RLOAD <= 2000.0.
Real FMAX
Is the line resistance scaling factor in pu 0.0 <= FMAX <= 0.1.
Integer NCHNG
Is returned as the number of branch resistances changed.
Integer IERR

IERR = 3, IRAT, RLOAD, or FMAX is in error.
1-96
PSS/E-29
POWER FLOW APIS

MOVE3WND
1.75 MOVE3WND
This API disconnects the second "to bus" of a specified three-winding transformer from the bus to
which it is currently connected, and reconnects it to a designated bus. The API is invoked by the use
of the statement:
MOVE3WND(FRMBUS, TOBUS1, TOBUS2, CKT, NEWTOBUS2, NEWCKT, IERR,
NERR)
or
BAT_MOVE3WND
NEWCKT
FRMBUS
TOBUS1
TOBUS2
CKT
NEWTOBUS2
where:
Integer FRMBUS
Is one of the buses connected by the three-winding transformer; the transformer will remain connected to this bus (input).
Integer TOBUS1
Is another bus connected by the three-winding transformer; the transformer will remain connected to this bus (input).
Integer TOBUS2
Is the third bus connected by the three-winding transformer; this connection will be severed and the transformer connected to bus NEWTOBUS2
(input).
Character CKT*2
Is the circuit identifier of the three-winding transformer to be rerouted

(input).
Integer NEWTOBUS2 Is the number of the bus to which the three-winding transformer is to be
connected (input).
Character NEWCKT*2 Is the new circuit identifier to be assigned to the rerouted three-winding
transformer (input).
Integer IERR

IERR = 1, FRMBUS, TOBUS1, TOBUS2, or NEWTOBUS2 not in
working case.
IERR = 2, circuit CKT connecting FRMBUS, TOBUS1, and TOBUS2 not
in working case.
IERR = 3, NEWTOBUS2 must be a bus other then FRMBUS, TOBUS1,
and TOBUS2.
IERR = 4, circuit NEWCKT connecting FRMBUS, TOBUS1, and
NEWTOBUS2 already in working case.
IERR = 5, invalid NEWCKT (must not start with "&").
Integer NERR
PSS/E-29
1-97
POWER FLOW APIS

MOVEBRN
1.76 MOVEBRN
This API disconnects the to bus of a specified non-transformer branch or two-winding transformer from the bus to which it is currently connected, and reconnects it to a designated bus. The
MOVEBRN(FRMBUS, TOBUS, CKT, NEWTOBUS, NEWCKT, IERR, NERR)
or
BAT_MOVEBRN
FRMBUS
TOBUS
CKT
NEWTOBUS
NEWCKT
where:
Integer FRMBUS
Is one of the buses connected by the branch; the branch will remain connected to this bus (input).
Integer TOBUS
Is the other bus connected by the branch; this connection will be severed
and the branch connected to bus NEWTOBUS (input).
Character CKT*2
Is the circuit identifier of the branch to be rerouted (input).
Integer NEWTOBUS
Is the number of the bus to which the branch is to be connected (input).
Character NEWCKT*2 Is the new circuit identifier to be assigned to the rerouted branch (input).
Integer IERR

IERR = 1, FRMBUS, TOBUS or NEWTOBUS not in working case.
case.
IERR = 3, NEWTOBUS must be a bus other then FRMBUS and TOBUS.
IERR = 4, circuit NEWCKT connecting FRMBUS and NEWTOBUS
already in working case.
IERR = 5, invalid NEWCKT (must not start with &).
Integer NERR
1-98
PSS/E-29
POWER FLOW APIS

MOVELOAD
1.77 MOVELOAD
This API disconnects the specified load from the bus to which it is currently connected, and reconnects it to a designated bus. The API is invoked by the use of the statement:
MOVELOAD(FRMBUS, ID, NEWBUS, NEWID, IERR, NERR)
or
BAT_MOVELOAD
FRMBUS
ID
NEWBUS
NEWID
where:
Integer FRMBUS
Is the bus to which load "ID" is connected (input).
Character ID*2
Is the load identifier of the load to be moved (input).
Integer NEWBUS
Is the number of the bus to which the load is to be moved (input).
Character NEWID*2
Is the new load identifier to be assigned to the relocated load (input).
Integer IERR

IERR = 1, FRMBUS or NEWBUS not in working case.
IERR = 3, FRMBUS and NEWBUS are the same bus.
IERR = 4, load NEWID at bus NEWBUS already in working case.
Integer NERR
PSS/E-29
1-99
POWER FLOW APIS

MOVELOADS
1.78 MOVELOADS
This API disconnects all of the load from the specified bus, and reconnects it to a designated bus.
Bus TOBUS must not have any load connected to it at the time this API is called. The API is
MOVELOADS(FRMBUS, TOBUS, IERR, NERR)
or
BAT_MOVELOADS
FRMBUS
TOBUS
where:
Integer FRMBUS
Is the bus on which one or more loads currently exist (input).
Integer TOBUS
Is the bus to which the loads on bus FRMBUS are to be moved (input).
Integer IERR

IERR = 2, no load present on bus FRMBUS.
IERR = 3, FRMBUS and TOBUS are the same bus.
IERR = 4, TOBUS already has loads (move individual loads).
Integer NERR
1-100
PSS/E-29
POWER FLOW APIS

MOVEMAC
1.79 MOVEMAC
This API disconnects the specified machine from the bus to which it is currently connected, and
reconnects it to a designated bus. The API is invoked by the use of the statement:
MOVEMAC(FRMBUS, ID, NEWBUS, NEWID, IERR, NERR)
or
BAT_MOVEMAC
FRMBUS
ID
NEWBUS
NEWID
where:
Integer FRMBUS
Character ID*2
Is the machine identifier of the machine to be moved (input).
Integer NEWBUS
Is the number of the bus to which the machine is to be moved (input).
Character NEWID*2
Is the new machine identifier to be assigned to the relocated machine

(input).
Integer IERR

IERR = 1, FRMBUS or NEWBUS not in working case.
IERR = 3, FRMBUS and NEWBUS are the same bus.
IERR = 4, machine NEWID at bus NEWBUS already in working case.
IERR = 5, plant table full (move machine to an existing plant).
Integer NERR
PSS/E-29
1-101
POWER FLOW APIS

MOVEPLNT
1.80 MOVEPLNT
This API disconnects all of the machines from the specified bus, and reconnects it to a designated
bus. Bus TOBUS must not have any plant data associated with it at the time this API is called. The
MOVEPLNT(FRMBUS, TOBUS, IERR, NERR)
or
BAT_MOVEPLNT
FRMBUS
TOBUS
where:
Integer FRMBUS
Is the bus on which plant data currently exists (input).
Integer TOBUS
Is the bus to which the plant on bus FRMBUS is to be moved (input).
Integer IERR

IERR = 2, no plant present on bus FRMBUS.
IERR = 4, TOBUS already has plant data (move individual machines).
Integer NERR
1-102
PSS/E-29
POWER FLOW APIS

MOVESWS
1.81 MOVESWS
This API disconnects the switched shunt load from the specified bus, and reconnects it to a designated bus. The API is invoked by the use of the statement:
MOVESWS(FRMBUS, TOBUS, IERR, NERR)
or
BAT_MOVESWS
FRMBUS
TOBUS
where:
Integer FRMBUS
Is the bus on which a switched shunt currently exists (input).
Integer TOBUS
Is the bus to which the switched shunt on bus FRMBUS is to be moved

(input).
Integer IERR

IERR = 2, no switched shunt present on bus FRMBUS.
Integer NERR
PSS/E-29
1-103
POWER FLOW APIS

MSLVAPI
1.82 MSLVAPI
This API executes activity MSLV. This API uses the default element specification as described in
MSLVAPI(OPTIONS, IERR, NERR)
or
BAT_MSLV
OPTIONS(5)
OPTIONS(1)
OPTIONS(6)
OPTIONS(2)
OPTIONS(3)
OPTIONS(4)
where:
Integer OPTIONS(6)
Is an array of six elements specifying solution options (input). The values

are as follows:
interchange.
interchange.
OPTIONS(6) = 0, apply var limits.
OPTIONS(6) = 1, ignore var limits.
1-104
PSS/E-29
POWER FLOW APIS

MSLVAPI
Integer IERR

Integer NERR
PSS/E-29
1-105
POWER FLOW APIS

MTDCAPI
1.83 MTDCAPI
This API executes activity MTDC. The API is invoked by the use of the statement:
MTDCAPI(IERR, NERR)
or
BAT_MTDC
where:
Integer IERR

IERR = 1, no unblocked multi-terminal dc lines in case.
Integer NERR
1-106
PSS/E-29
POWER FLOW APIS

MULTISECTION_LINE_REPORTING_API
1.84 MULTISECTION_LINE_REPORTING_API
This API is used to set the value of the multi-section line reporting option setting to either "off" or
"on". The API is invoked by the use of the statement:
MULTISECTION_LINE_REPORTING_API(IVAL, IOCODE, IERR, NERR)
or
BAT_MULTISECTION_LINE_REPORTING
IVAL
where:
Integer IVAL

IVAL = 0, off.
IVAL = 1, on.
Integer IOCODE

Integer IERR

Integer NERR
PSS/E-29
1-107
POWER FLOW APIS

NETGNW
1.85 NETGNW
This API is used to change the in-service generation to negative MVA load at all type two and three
buses except those within the subsystem specified by the user. The API is invoked by use of the
statement:
NETGNW(SID, ALL, IERR)
or:
BAT_NETG
SID
ALL
where:
Integer SID

Integer ALL

Integer IERR

1-108
PSS/E-29
POWER FLOW APIS

NEWCASNW
1.86 NEWCASNW
This API is used to initialize a new power flow case. All existing power flow data will be lost upon
execution of this API. The API is invoked by the use of the statement:
NEWCASNW(BASEKV, TITL1, TITL2, IERR)
or:
BAT_NEWCAS
BASEKV TITL1 TITL2
where:
Real BASEKV
Is the new system base kV. Valid base kV values range from 1 to
10,000.
CHARACTER TITL1*60
Is the first line of the new case title.
CHARACTER TITL2*60
Is the second line of the new case title.
Integer IERR

IERR = 1, base kV is in error.
PSS/E-29
1-109
POWER FLOW APIS

NEWTON_TOLERANCE_API
1.87 NEWTON_TOLERANCE_API
This API is used to set the value of the default Newton-Raphson convergence tolerance option setting. The API is invoked by the use of the statement:
CALL NEWTON_TOLERANCE_API(RVAL, IOCODE, IERR, NERR)
or
BAT_NEWTON_TOLERANCE_FACTOR
RVAL
where:
Integer RVAL

Integer IOCODE

Integer IERR

Integer NERR
1-110
PSS/E-29
POWER FLOW APIS

NON_DIVERGENT_API
1.88 NON_DIVERGENT_API
This API is used to set the value of the non-divergent Newton power flow solution option setting to
either "enabled" or "disabled". The API is invoked by the use of the statement:
NON_DIVERGENT_API(IVAL, IOCODE, IERR, NERR)
or
BAT_NON_DIVERGENT
IVAL
where:
Integer IVAL

IVAL = 0, disable non-divergent Newton solution option.
IVAL = 1, enable non-divergent Newton solution option.
Integer IOCODE

Integer IERR

Integer NERR
PSS/E-29
1-111
POWER FLOW APIS

NRDFLT
1.89 NRDFLT
This subroutine returns the default solution options for the Newton-Raphson based solution activities FNSL, FDNS, NSOL, ACCC and INLF. The API is invoked by the use of the statement:
NRDFLT(METHOD, TAPOPT, INTOPT, PHSOPT, DCOPT, SWSOPT, VARLIM,
IERR, NERR)
where:
Integer METHOD
Is the flag indication solution method (input).

METHOD = 1, FNSL, FDNS or NSOL.
METHOD = 2, ACCC.
METHOD = 3, INLF inertial load flow.
METHOD = 4, INLF governor response load flow.
Integer TAPOPT
Is the tap adjustment flag (output).

TAPOPT = 0, disabled.
TAPOPT = 1, enabled using discrete stepping method.
TAPOPT = 2, enabled using direct method.
Integer INTOPT
Is the area interchange adjustment flag (output).

INTOPT = 0, disabled.
INTOPT = 1, enabled using tie line flows only in calculating area
interchange.
INTOPT = 2, enabled using tie line flows and loads in calculating area
interchange.
Integer PHSOPT
Is the phase shifter adjustment flag (output)

PHSOPT = 0, disabled.
PHSOPT = 1, enabled.
Integer DCOPT
Is the dc tap adjustment flag (output).

DCOPT = 0, disabled.
DCOPT = 1, enabled.
Integer SWSOPT
Is the switched shunt adjustment flag (output).

SWSOPT = 0, disabled.
SWSOPT = 1, enabled.
Integer VARLIM
Is the var limit application flag (output).

VARLIM = 0, apply immediately.
VARLIM = -1, ignore.
VARLIM = n, iteration number on which they are to be first applied (n>0).
1-112
PSS/E-29
POWER FLOW APIS

NRDFLT
Integer IERR

IERR = 1, invalid METHOD value.
Integer NERR
PSS/E-29
1-113
POWER FLOW APIS

NSOLAPI
1.90 NSOLAPI
This API executes activity NSOL. This API uses the default element specification as described in
NSOLAPI(OPTIONS, IERR, NERR)
or
BAT_NSOL
OPTIONS(5)
OPTIONS(1) OPTIONS(2)
OPTIONS(6) OPTIONS(7)
OPTIONS(3)
OPTIONS(4)
where:
Integer OPTIONS(7)

interchange.
interchange.
1-114
PSS/E-29
POWER FLOW APIS

NSOLAPI

gets small).
Integer IERR

Integer NERR
PSS/E-29
1-115
POWER FLOW APIS

ORDRAPI
1.91 ORDRAPI
This API executes activity ORDR. The API is invoked by the use of the statement:
ORDRAPI(OPT, IERR, NERR)
or
BAT_ORDR
OPT
where:
Integer OPT
Is the flag for ordering option (input).

OPT = 0, assume all branches between in-service buses are in-service.
OPT = 1, ignore out-of-service branches in calculating the bus ordering.
Integer IERR

IERR = 1, invalid OPT.
Integer NERR
1-116
PSS/E-29
POWER FLOW APIS

OTDFAPI
1.92 OTDFAPI
This API executes activity OTDF. The API is invoked by the use of the statement:
OTDFAPI(DFXFILE, IERR, NERR)
or
BAT_OTDF
DFXFILE
where:
Integer IERR

IERR = 2, subroutine GETLOS error (generators are "converted" or
swingless island present).
Integer NERR
PSS/E-29
1-117
POWER FLOW APIS

OUTSNW
1.93 OUTSNW
This API is used to tabulate those components in the working case that are removed from service.
OUTSNW(SID, ALL, IERR)
or:
BAT_OUTS
SID
ALL
where:
Integer SID
Integer ALL

Integer IERR

1-118
PSS/E-29
POWER FLOW APIS

OWNMAPI
1.94 OWNMAPI
This API is used to reassign the buses, load, machines, and branches in a selected subsystem of the
working case from their original owner to a designated owner. The API is invoked by the use of the
statement:
OWNMAPI(SID, ALL, STATUS, IONEW, IERR, NERR)
or:
BAT_OWNM
STATUS(5)
SID ALL STATUS(1)

STATUS(6) STATUS(7)
STATUS(2)
IONEW
STATUS(3)
STATUS(4)
where:
Integer SID

Integer ALL

Integer STATUS(7)
Is an array of seven elements (input). They are used to control reassignment

options.
STATUS(1) = 1, change bus owners to IONEW; otherwise = 0.
STATUS(2) = 1, change load owners to IONEW; otherwise = 0.
STATUS(3) = 1, change machine owners to IONEW; otherwise = 0.
STATUS(4) = 1, change branch owners to IONEW; otherwise = 0.
STATUS(5) = 1, change FACTS device owners to IONEW; otherwise = 0.
STATUS(5) = 1, change VSC dc line owners to IONEW; otherwise = 0.
STATUS(7), branch, series FACTS device, VSC dc line option.
STATUS(7) = 1, subsystem branches only.
STATUS(7) = 2, subsystem ties only.
STATUS(7) = 3, both subsystem branches and ties.
Integer IONEW
Is the new owner to assign the selected buses to (input). IONEW must be
between 1 and OWNERS.
Integer IERR

IERR = 3, IONEW is not between 1 and OWNERS.
Integer NERR
PSS/E-29
1-119
POWER FLOW APIS

OWNRNW
1.95 OWNRNW
This API is used to provide a tabulation by owner interchange of the desired owner net interchange.
OWNRNW(SID, ALL, IERR)
or:
BAT_OWNR
SID
ALL
where:
Integer SID

Integer ALL
Is the "all" owners or selected subsystem flag (input).

ALL = 1, process all owners.
ALL = 0, process only selected owners.
Integer IERR

1-120
PSS/E-29
POWER FLOW APIS

PP_ACCC
1.96 PP_ACCC
This API is used to invoke the AC Contingency Calculation report process. The API is invoked by
PP_ACCC(STATUS, INTVAL, REALVAL, RFILE, IERR)
or:
BAT_PPACCC
STATUS(1) STATUS(2) STATUS(3) STATUS(4) STATUS(5)
INTVAL(1) INTVAL(2) INTVAL(3) INTVAL(4) INTVAL(5) REALVAL(1)
REALVAL(2) REALVAL(3) REALVAL(4) REALVAL(5) REALVAL(6) RFILE
where:
Integer STATUS(5)
Is an array of five elements. The values are as follows.

STATUS(1), Contingency case rating.
STATUS(1) = 0, Rate A.
STATUS(1) = 1, Rate B.
STATUS(1) = 2, Rate C.
STATUS(2), Report format.
STATUS(2) = 0, Spreadsheet overload report.
STATUS(2) = 1, Spreadsheet loading table.
STATUS(2) = 2, Available capacity table.
STATUS(2) = 3, Non-spreadsheet overload report.
STATUS(2) = 4, Non-spreadsheet loading table.
STATUS(3), Exclude interfaces from report.
STATUS(3) = 0, No.
STATUS(3) = 1, Yes.
STATUS(4), Perform voltage limit check.
STATUS(4) = 0, No.
STATUS(4) = 1, Yes.
STATUS(5), Exclude cases with no overloads from non-spreadsheet overload report.
STATUS(5) = 0, No.
STATUS(5) = 1, Yes.
PSS/E-29
1-121
POWER FLOW APIS

PP_ACCC
Integer INTVAL(5)
Is an array of five elements. The values are as follows.

INTVAL(1), Number of low voltage range violations.
INTVAL(2), Number of high voltage range violations.
INTVAL(3), Number of voltage deviation violations.
INTVAL(4), Number of buses in the largest disconnected island.
INTVAL(5), Maximum elements in available capacity table.
Integer REALVAL(4) Is an array of four elements. The values are as follows.

REALVAL(1), Percent of flow rating.
REALVAL(2), Minimum contingency case flow change for overload
report.
REALVAL(3), Cutoff threshold for available capacity table.
REALVAL(4), Minimum contingency case voltage change for range
violations.
REALVAL(5), Bus mismatch tolerance (MW or Mvar).
REALVAL(6), System mismatch tolerance (MVA).
Character*260 RFILE Is the AC Contingency Calculation solution output data file.
Integer IERR

IERR = 1, Error in STATUS.
IERR = 2, Error in INTVAL.
IERR = 3, Error in REALVAL.
IERR = 4, Error in RFILE.
1-122
PSS/E-29
POWER FLOW APIS

PATHAPI
1.97 PATHAPI
This API executes activity PATH. The API is invoked by the use of the statement:
PATHAPI(PATHNAME, IERR, NERR)
or
BAT_PATH
PATHNAME
where:
Character PATHNAME*260 Is the name of path to be used (blank to disable) (input).
Integer IERR

IERR = 1, error setting path PATHNAME.
Integer NERR
PSS/E-29
1-123
POWER FLOW APIS

PHASE_SHIFT_ADJUSTMENT_API
1.98 PHASE_SHIFT_ADJUSTMENT_API
This API is used to set the value of the phase shift adjustment option setting to either "disabled" or
"enabled (on)". The API is invoked by the use of the statement:
PHASE_SHIFT_ADJUSTMENT_API(IVAL, IOCODE, IERR, NERR)
or
BAT_PHASE_SHIFT_ADJUSTMENT
IVAL
where:
Integer IVAL

IVAL = 0, disabled.
IVAL = 1, enabled.
Integer IOCODE

Integer IERR

Integer NERR
1-124
PSS/E-29
POWER FLOW APIS

POLYAPI
1.99 POLYAPI
This API executes activity POLY. The API is invoked by the use of the statement:
CALL POLYAPI(OPTIONS, TOLS, LABELS, DFXFILE, IERR, NERR)
or
BAT_POLY
OPTIONS(1) . . . OPTIONS(15)
LABELS(1) . . . LABELS(3) DFXFILE
TOLS(1) . . . TOLS(6)
where:
Integer OPTIONS(15) Is an array of fifteen elements specifying calculation and reporting options
OPTIONS(1), base case rating set.
OPTIONS(4), phase shifter code.
OPTIONS(4) = 0, locked in base case shift solutions.
OPTIONS(4) = 1, regulating in base case shift solutions.
OPTIONS(5), code for the treatment of base case line flow constraints in
contingency cases.
OPTIONS(5) = 0, ignore.
OPTIONS(6), list study system buses.
OPTIONS(6) = 0, no.
OPTIONS(7), list opposing system buses.
OPTIONS(7) = 0, no.
PSS/E-29
1-125
POWER FLOW APIS

POLYAPI
OPTIONS(8), list study system tie lines.

OPTIONS(8) = 0, no.
OPTIONS(9), add study system tie lines to monitored line list.
OPTIONS(9) = 0, no.
OPTIONS(11) = 0, no.
OPTIONS(12), abort if MW mismatch exceeds TOLS(1).
OPTIONS(13), graphical output option.
OPTIONS(13) = 0, none.
OPTIONS(13) = 1, plot "combined" case only.
OPTIONS(13) = 2, plot for all system conditions.
OPTIONS(14), option for plotting constraints.
OPTIONS(14) = 0, plot all constraints.
OPTIONS(14) = 1, plot only constraints forming the boundary of the feasible region.
OPTIONS(15), graphical output format.
OPTIONS(15) = 0, single page per case.
OPTIONS(15) = 1, two pages per case.
Real TOLS(6)
Is an array of six elements specifying tolerances and thresholds (input).

TOLS(2), percent of rating for reporting an element as overloaded.
TOLS(3), maximum opposing system generation shift.
TOLS(4), maximum opposing system delta interchange for plotting.
TOLS(5), minimum distribution factor magnitude.
TOLS(6), study system generation shift.
Character LABELS*12 Is an array of three elements specifying subsystem labels (input).

LABELS(1), study system label.
LABELS(2), first opposing system label.
LABELS(3), second opposing system label.
1-126
PSS/E-29
POWER FLOW APIS

POLYAPI
Integer IERR

IERR = 0, no error.
IERR = 3, invalid TOLS value.
IERR = 7, same subsystem label specified for study and opposing
subsystems.
Integer NERR
PSS/E-29
1-127
POWER FLOW APIS

POUTNW
1.100 POUTNW
This API is used to print power flow data. The API is invoked by the use of the statement:
POUTNW(SID, ALL, IERR)
or:
BAT_POUT
SID
ALL
where:
Integer SID
Integer ALL

Integer IERR

1-128
PSS/E-29
POWER FLOW APIS

POWER_OUTPUT_API
1.101 POWER_OUTPUT_API
This API is used to set the value of the power outout option setting to either "MVA" or "KVA". The
POWER_OUTPUT_API(IVAL, IOCODE, IERR, NERR)
or
BAT_POWER_OUTPUT
IVAL
where:
Integer IVAL

IVAL = 0, KVA.
IVAL = 1, MVA.
Integer IOCODE

Integer IERR

Integer NERR
PSS/E-29
1-129
POWER FLOW APIS

PRTIAPI
1.102 PRTIAPI
This API executes activity PRTI. The API is invoked by the use of the statement:
PRTIAPI(IERR, NERR)
or
BAT_PRTI
where:
Integer IERR

Integer NERR
1-130
PSS/E-29
POWER FLOW APIS

PURG2DC
1.103 PURG2DC
This API deletes the specified two-terminal dc line from the working case. The API is invoked by
PURG2DC(DC, IERR, NERR)
or
BAT_PURG2DC
DC
where:
Integer DC
Is the number of the two-terminal dc line to be removed (input).
Integer IERR

IERR = 1, invalid dc line number.
Integer NERR
PSS/E-29
1-131
POWER FLOW APIS

PURG3WND
1.104 PURG3WND
This API deletes the specified three-winding transformer from the working case. The API is
PURG3WND(FRMBUS, TOBUS1, TOBUS2, CKT, IERR, NERR)
or
BAT_PURG3WND
FRMBUS
TOBUS1
TOBUS2
CKT
where:
Integer FRMBUS
Is one of the buses connected by the three-winding transformer (input).
Integer TOBUS1
Is another bus connected by the three-winding transformer (input).
Integer TOBUS2
Is the other bus connected by the three-winding transformer (input).
Character CKT*2
Is the circuit identifier of the three-winding transformer to be deleted

(input).
Integer IERR

IERR = 1, FRMBUS, TOBUS1 or TOBUS2 not in working case.
IERR = 2, circuit CKT connecting FRMBUS, TOBUS1 and TOBUS2 not
in working case.
Integer NERR
1-132
PSS/E-29
POWER FLOW APIS

PURGATRN
1.105 PURGATRN
This API deletes the specified inter-area transfer from the working case. The API is invoked by the
PURGATRN(FRMAREA, TOAREA, ID, IERR, NERR)
or
BAT_PURGATRN
FRMAREA
TOAREA
ID
where:
Integer FRMAREA
Is one of the areas involved in the transfer (input).
Integer TOAREA
Is the other area involved in the transfer (input).
Character ID*1
Is the inter-area transfer identifier (input).
Integer IERR

IERR = 1, FRMAREA or TOAREA is invalid area number.
IERR = 2, inter-area transfer ID between areas FRMAREA and TOAREA
not in working case.
Integer NERR
PSS/E-29
1-133
POWER FLOW APIS

PURGBRN
1.106 PURGBRN
This API deletes the specified non-transformer branch or two-winding transformer from the
PURGBRN(FRMBUS, TOBUS, CKT, IERR, NERR)
or
BAT_PURGBRN
FRMBUS
TOBUS
CKT
where:
Integer FRMBUS
Is one of the buses connected by the branch (input).
Integer TOBUS
Is the other bus connected by the branch (input).
Character CKT*2
Is the circuit identifier of the branch to be deleted (input).
Integer IERR

case.
Integer NERR
1-134
PSS/E-29
POWER FLOW APIS

PURGFACTS
1.107 PURGFACTS
This API deletes the specified FACTS device from the working case. The API is invoked by the use
of the statement:
PURGFACTS(DEVICE, IERR, NERR)
or
BAT_PURGFACTS
DEVICE
where:
Integer DEVICE
Is the number of the FACTS device to be removed (input).
Integer IERR

IERR = 1, invalid FACTS device number.
IERR = 2, FACTS device DEVICE not in working case.
Integer NERR
PSS/E-29
1-135
POWER FLOW APIS

PURGLOAD
1.108 PURGLOAD
This API deletes the specified load from the working case. The API is invoked by the use of the
statement:
PURGLOAD(FRMBUS, ID, IERR, NERR)
or
BAT_PURGLOAD
FRMBUS
ID
where:
Integer FRMBUS
Is the bus to which load ID is connected (input).
Character ID*2
Is the machine identifier of the load to be removed (input).
Integer IERR

Integer NERR
1-136
PSS/E-29
POWER FLOW APIS

PURGLOADS
1.109 PURGLOADS
This API deletes all loads from the specified bus in the working case. The API is invoked by the use
of the statement:
PURGLOADS(FRMBUS, IERR, NERR)
or
BAT_PURGLOADS
FRMBUS
where:
Integer FRMBUS
Is the bus at which all loads are to be removed (input).
Integer IERR

IERR = 2, no loads at bus FRMBUS.
Integer NERR
PSS/E-29
1-137
POWER FLOW APIS

PURGMAC
1.110 PURGMAC
This API deletes the specified machine from the working case. The API is invoked by the use of the
statement:
PURGMAC(FRMBUS, ID, IERR, NERR)
or
BAT_PURGMAC
FRMBUS
ID
where:
Integer FRMBUS
Character ID*2
Is the machine identifier of the machine to be removed (input).
Integer IERR

Integer NERR
1-138
PSS/E-29
POWER FLOW APIS

PURGMDC
1.111 PURGMDC
This API deletes the specified multi-terminal dc line from the working case. The API is invoked by
PURGMDC(DC, IERR, NERR)
or
BAT_PURGMDC
DC
where:
Integer DC
Is the number of the multi-terminal dc line to be removed (input).
Integer IERR

Integer NERR
PSS/E-29
1-139
POWER FLOW APIS

PURGMSL
1.112 PURGMSL
This API deletes the specified multi-section line grouping from the working case. The API is
PURGMSL(FRMBUS, TOBUS, CKT, IERR, NERR)
or
BAT_PURGMSL
FRMBUS
TOBUS
CKT
where:
Integer FRMBUS
Is one of the endpoint buses of the multi-section line (input).
Integer TOBUS
Is the other endpoint bus of the multi-section line (input).
Character CKT*2
Is the circuit identifier of the multi-section line to be deleted; the first character must be an ampersand (input).
Integer IERR

IERR = 2, invalid multi-section line identifier (first character not "&").
IERR = 3, multi-section line CKT between FRMBUS and TOBUS not in
working case.
Integer NERR
1-140
PSS/E-29
POWER FLOW APIS

PURGMUT
1.113 PURGMUT
This API deletes the specified zero sequence mutual coupling from the working case. The API is
PURGMUT(FRMBUS1, TOBUS1, CKT1, FRMBUS2, TOBUS2, CKT2, IERR, NERR)
or
BAT_PURGMUT
FRMBUS1
TOBUS1
CKT1
FRMBUS2
TOBUS2
CKT2
where:
Integer FRMBUS1
Is one of the buses connected by the first branch of the mutual coupling
(input).
Integer TOBUS1
Is the other bus connected by the first branch of the mutual coupling
(input).
Character CKT1*2
Is the circuit identifier of the first branch of the mutual coupling (input).
Integer FRMBUS2
Is one of the buses connected by the second branch of the mutual coupling
(input).
Integer TOBUS2
Is the other bus connected by the second branch of the mutual coupling
(input).
Character CKT2*2
Is the circuit identifier of the second branch of the mutual coupling (input).
Integer IERR

IERR = 1, FRMBUS1, TOBUS1, FRMBUS2 or TOBUS2 not in working
case.
IERR = 2, circuit CKT1 connecting FRMBUS1 and TOBUS1 not in
working case.
IERR = 3, circuit CKT2 connecting FRMBUS2 and TOBUS2 not in
working case.
IERR = 4, mutual coupling not in working case,
IERR = 5, sequence data not in working case.
Integer NERR
PSS/E-29
1-141
POWER FLOW APIS

PURGNW
1.114 PURGNW
This API is used to delete designated outaged equipment items from the working case. The API is
PURGNW(SID, ALL, OPT, STATUS, IERR)
or:
BAT_PURG
SID
ALL
OPT
STATUS
where:
Integer SID
Integer ALL

Integer OPT
Is the equipment type to remove.

= 1, ac lines
= 3, machines
= 5, two-terminal dc lines
= 7, loads
= 9, three-winding transformers
= 2, switched shunts
= 4, plants
= 6, multiterminal dc lines
= 8, FACTS control devices
=10, VSC dc lines
Integer STATUS
Is the status of out-of-service ties to other systems.

STATUS = 0, leave out-of-service ties.
STATUS = 1, remove out-of-service ties to other systems.
Integer IERR

IERR = 0, no error.
IERR = 2, STATUS and/or OPT is in error.
1-142
PSS/E-29
POWER FLOW APIS

PURGPLNT
1.115 PURGPLNT
This API deletes the plant and machine data at the specified bus from the working case. The API is
PURGPLNT (FRMBUS, IERR,NERR)
or
BAT_PURGPLNT
FRMBUS
where:
Integer FRMBUS
Is the bus whose plant is to be removed (input).
Integer IERR

IERR = 2, no plant at bus FRMBUS.
Integer NERR
PSS/E-29
1-143
POWER FLOW APIS

PURGSWS
1.116 PURGSWS
This API deletes the specified switched shunt from the working case. The API is invoked by the use
of the statement:
PURGSWS(FRMBUS, IERR, NERR)
or
BAT_PURGSWS
FRMBUS
where:
Integer FRMBUS
Is the bus whose switched shunt is to be removed (input).
Integer IERR

IERR = 2, no switched shunt on bus FRMBUS.
Integer NERR
1-144
PSS/E-29
POWER FLOW APIS

PURGVSC
1.117 PURGVSC
This API deletes the specified VSC dc line from the working case. The API is invoked by the use
of the statement:
PURGVSC(NAME, IERR, NERR)
or
BAT_PURGVSC
NAME
where:
Character NAME*8
Is the name of the VSC dc line to be removed (input).
Integer IERR

IERR = 1, VSC dc line NAME not in working case.
Integer NERR
PSS/E-29
1-145
POWER FLOW APIS

RANKNW
1.118 RANKNW
This API is used to estimate the severity of designated single branch outage contingencies and
builds a Contingency Description Data File with contingencies specified in decreasing order of their
estimated severities. The API is invoked by the use of the statement:
RANKNW(SID, ALL, IVAL, RVAL, SSFILE, MNFILE, OFILE, IERR)
or:
BAT_RANK
SID ALL IVAL(1) IVAL(2) IVAL(3) IVAL(4) IVAL(5)
IVAL(6) IVAL(7) RVAL(1) RVAL(2) RVAL(3) RVAL(4) SSFILE
MNFILE OFILE
where:
Integer SID

Integer ALL

Integer IVAL(7)
Is an array of seven elements. They are used to control ranking options.

IVAL(1) = 1, allow ties from specified subsystem as contingencies;
otherwise = 0.
IVAL(2), number of overloaded contingencies to include (>= 0).
IVAL(3), rating set (1=RATEA, 2=RATEB, 3=RATEC).
IVAL(4) = 1, convert ratings to estimated MW ratings; otherwise = 0.
IVAL(5), number of voltage depression contingencies to include (>=0).
IVAL(6) = 0, include all branches in the voltage depression performance
index; = 1 to include only those with a nonzero rating.
IVAL(7) = 1, include contingencies that create swingless islands;
otherwise = 0.
Real RVAL(4)
Is an array of four elements. They are used as ranking parameters.

RVAL(1), MW mismatch threshold (>= 0.).
RVAL(2), small reactance threshold (THRSHZ <= RVAL(2) <= 0.005).
RVAL(3), percent of rating (0. <= RVAL(3) <= 200.).
RVAL(4), MW threshold for islanding contingencies (>= 0.).
Character SSFILE*260 Is the Subsystem Description data filename or blank for no subsystem
input.
Character MNFILE*260 Is the Monitored Element data filename.
Character OFILE*260 Is the output Contingency Description data filename or blank for output to the
progress window.
1-146
PSS/E-29
POWER FLOW APIS

RANKNW
Integer IERR
PSS/E-29

IERR = 0, no error.
IERR = 2, SSFILE and/or MNFILE is in error.
IERR = 3, IVAL or RVAL error.
IERR = 4, OFILE error.
1-147
POWER FLOW APIS

RATENW
1.119 RATENW
This API is used to check branch current loadings. The API is invoked by the use of the statement:
RATENW(SID, ALL, IACT, IFL, FMAX, IERR)
or:
BAT_RATE
SID
ALL
IACT
IFL
FMAX
where:
Integer SID
Integer ALL

Integer IACT
Is the branch check to be performed.

IACT = 1, check all lines.
IACT = 2, check transmission lines.
IACT = 3, check transformers.
IACT = 4, check all lines, all ratings.
Integer IFL
Is the rating to be used.

IACT = 1, RATEA.
IACT = 2, RATEB.
IACT = 3, RATEC.
Real FMAX
Is the line loading limit, in percent; 0.0 =< FMAX =< 500.0.
Integer IERR

IERR = 0, no error.
IERR = 2, either IACT, ITL, or FMAX is in error.
1-148
PSS/E-29
POWER FLOW APIS

RATING_SET_API
1.120 RATING_SET_API
This API is used to set the value of the default rating set option setting to either "RATEA",
"RATEB" or "RATEC". The API is invoked by the use of the statement:
RATING_SET_API(IVAL, IOCODE, IERR, NERR)
or
BAT_RATING_SET
IVAL
where:
Integer IVAL

IVAL = 1, RATEA.
IVAL = 2, RATEB.
IVAL = 3, RATEC.
Integer IOCODE

Integer IERR

Integer NERR
PSS/E-29
1-149
POWER FLOW APIS

RAWDAPI
1.121 RAWDAPI
This API outputs the working case in the form of a Power Flow Raw Data file (activity RAWD).
RAWDAPI(SID, ALL, STATUS, OUT, OFILE, IERR, NERR)
or:
BAT_RAWD
STATUS(5)

STATUS(6) OUT OFILE
STATUS(3)
STATUS(4)
where:
Integer SID
Integer ALL

ALL = 0, process subsystem SID.
Integer STATUS(6)
Is an array of six elements specifying output options. The values are as

follows:
STATUS(1), include records for type 4 buses (0 = no, 1 = yes).
STATUS(2), include records for out-of-service branches (0 = no, 1 = yes).
STATUS(3), include records for equipment within the subsystem (0 = no,
1 = yes).
STATUS(4), include records for subsystem ties (0 = no, 1 = yes).
STATUS(5), use bus names as bus identifiers (0 = no, 1 = yes).
STATUS(6), Raw Data File type.
STATUS(6) = 0, for activity READ with IC=0.
STATUS(6) = 1, for activity READ with IC=1.
STATUS(6) = 2, for activity RDCH.
Integer OUT
Is the output destination selection (input).

Character OFILE*260 Is the name of the file to which data records are to be written (input).
Integer IERR
1-150

IERR = 0, no error.
IERR = 2, SID or ALL is in error (invalid value or subsystem SID not
defined).
IERR = 3, STATUS value is in error.
PSS/E-29
POWER FLOW APIS

RAWDAPI
IERR = 4, OUT value is in error.

IERR = 5, error opening file OFILE.
Integer NERR
PSS/E-29
1-151
POWER FLOW APIS

RAWDNW
1.122 RAWDNW
This API is used to write out the working case in the form of a Load Flow Raw Data file. The API
RAWDNW(SID, ALL, STATUS, OUT, OFILE, IERR)
or:
BAT_RAWD
STATUS(5)
SID ALL STATUS(1)

OUT OFILE
STATUS(2)
STATUS(3)
STATUS(4)
where:
Integer SID
Integer ALL

Integer STATUS(5)
Is an array of five elements. They are used to control output options. A value
STATUS(1), omit isolated buses.
STATUS(2), omit out-of-service branches.
STATUS(3), include subsystem data.
STATUS(4), include subsystem ties.
STATUS(5), 0 = bus numbers, 1 = bus names.
Integer OUT

Character OFILE*260 Is the working case data output file.

Integer IERR
1-152

IERR = 0, no error.
PSS/E-29
POWER FLOW APIS

RDCHAPI
1.123 RDCHAPI
This API executes activity RDCH. The API is invoked by the use of the statement:
RDCHAPI(NUMNAM, FILE, IERR, NERR)
or
BAT_RDCH
NUMNAM
FILE
where:
Integer NUMNAM
Is the flag for bus number or name specification on input records (input).
NUMNAM = 0, bus numbers.
NUMNAM = 1, bus names.
Character FILE*260
Is the filename of Raw Data Input file (input).
Integer IERR

IERR = 1, invalid NUMNAM.
Integer NERR
PSS/E-29
1-153
POWER FLOW APIS

RDEQNW
1.124 RDEQNW
This API is used to equivalence radial and, optionally. "two point" type one buses in all but specified subsystems of the working case. The API is invoked by the use of the statement:
RDEQNW(SID, ALL, STATUS, IERR)
or:
BAT_RDEQ
STATUS(5)

STATUS(6) STATUS(7) STATUS(8)
STATUS(3)
STATUS(4)
where:
Integer SID
Integer ALL

Integer STATUS(8)
Is an array of eight elements. They are used to control equivalencing options.

A value of 0 means the option is not enabled. A value of 1 means the option is
STATUS(1), equivalence radial buses only.
STATUS(2), suppress equivalencing of transformers.
STATUS(3), suppress equivalencing of zero impedance lines.
STATUS(4), suppress equivalencing of controlled buses.
STATUS(5), suppress equivalencing of mutually coupled branches.
STATUS(6), suppress equivalencing of area boundary buses.
STATUS(7), suppress equivalencing of zone boundary buses.
STATUS(8), apply transformer impedance correction to zero sequence
lines.
Integer IERR

IERR = 0, no error.
1-154
PSS/E-29
POWER FLOW APIS

READAPI
1.125 READAPI
This API executes activity READ, with all data in the input file being added to the working case.
READAPI(NUMNAM, FILE, IERR, NERR)
or
BAT_READ
NUMNAM
FILE
where:
Integer NUMNAM
Character FILE*260
Is the filename of Power Flow Raw Data Input file (input).
Integer IERR

Integer NERR
PSS/E-29
1-155
POWER FLOW APIS

READSUB
1.126 READSUB
This API executes activity READ, with subsystem data in the input file being added to the working
case. The API is invoked by the use of the statement:
READSUB(NUMNAM, FILE, STATUS, USEKV, BASEKV, SIDAREA, SIDOWNER,
SIDZONE, IERR, NERR)
or
BAT_READSUB
NUMNAM FILE STATUS(1) STATUS(2) STATUS(3)
USEKV BASEKV(1) BASEKV(2) SIDAREA SIDOWNER SIDZONE
where:
Integer NUMNAM
Character FILE*260
Is the filename of Raw Data Input file (input).
Integer STATUS(3)
Is an array of three elements specifying READ options (input). The values

are as follows:
STATUS(1), append flag.
STATUS(1) = 0, initialize working case before reading data.
STATUS(1) = 1, append data to that already in the working case.
STATUS(2), boundary bus identification flag.
STATUS(2) = 0, do not change type codes of boundary buses.
STATUS(2) = 1, change type codes of boundary buses in preparation for
equivalencing
STATUS(3), data input option.
STATUS(3) = 1, add only data from within subsystem.
STATUS(3) = 2, add only ties from subsystem.
STATUS(3) = 3, add subsystem data plus ties.
Integer USEKV
Is the specify subsystem by base voltage (input).

USEKV = 0, do not use base voltage as a subsystem selection criterion.
USEKV = 1, use base voltage as a subsystem selection criterion.
Real BASEKV(2)
Is an array of two elements specifying the base voltage range (input).

BASEKV(1), is the minimum base voltage.
BASEKV(2), is the maximum base voltage.
Integer SIDAREA
Is the area subsystem ID (0 through 3), or 1 to bypass subsystem specification by area (input).
1-156
PSS/E-29
POWER FLOW APIS

READSUB
Integer SIDOWNER
Is the owner subsystem ID (0 through 3), or 1 to bypass subsystem specification by owner (input).
Integer SIDZONE
Is the zone subsystem ID (0 through 3), or 1 to bypass subsystem specification by zone (input).
Integer IERR

IERR = 4, invalid USEKV value.
IERR = 5, invalid BASEKV value(s).
IERR = 6, invalid SIDAREA value.
IERR = 7, invalid SIDOWNER value.
IERR = 8, invalid SIDZONE value.
IERR = 9, no subsystem specified.
Integer NERR
PSS/E-29
1-157
POWER FLOW APIS

RECNAPI
1.127 RECNAPI
This API executes activity RECN. The API is invoked by the use of the statement:
RECNAPI(BUS, IERR, NERR)
or
BAT_RECN
BUS
where:
Integer BUS
Is the bus number of bus to be reconnected (input).
Integer IERR

IERR = 1, bus BUS not in working case.
Integer NERR
1-158
PSS/E-29
POWER FLOW APIS

REGBNW
1.128 REGBNW
This API is used to tabulate those buses whose voltages are controlled by generation, switched
shunts and/or voltage controlling transformers. The API is invoked by the use of the statement:
REGBNW(SID, ALL, IERR)
or:
BAT_REGB
SID
ALL
where:
Integer SID
Integer ALL

Integer IERR

IERR = 0, no error.
PSS/E-29
1-159
POWER FLOW APIS

REMMAPI
1.129 REMMAPI
This API executes activity REMM. The API is invoked by the use of the statement:
REMMAPI(OPT, FILE, IERR, NERR)
or
BAT_REMM
OPT
FILE
where:
Integer OPT
Is the flag for new or change data input records (input).

OPT = 0, new data; replaces existing transactions data.
OPT = 1, change data; modifies existing transactions data.
Character FILE*260
Is the filename of Transactions Raw Data Input file (input).
Integer IERR

IERR = 2, invalid change mode.
Integer NERR
1-160
PSS/E-29
POWER FLOW APIS

RESQAPI
1.130 RESQAPI
This API executes activity RESQ, with all data in the input file being added to the working case.
RESQAPI(FILE, IERR)
or
BAT_RESQ
FILE
where:
Character FILE*260
Is the filename of Sequence Data Input file (input).
Integer IERR

PSS/E-29
1-161
POWER FLOW APIS

RETIAPI
1.131 RETIAPI
This API executes activity RETI, with data read from the input file. The API is invoked by the use
of the statement:
CALL RETIAPI(FILE, IERR, NERR)
or
BAT_RETI
FILE
where:
Character FILE*260
Is the filename of Long Title Data Input File (input).
Integer IERR

Integer NERR
1-162
PSS/E-29
POWER FLOW APIS

RNFIAPI
1.132 RNFIAPI
This API executes activity RNFI. The API is invoked by the use of the statement:
CALL RNFIAPI(TYPE, TRNFILE, INPFILE, OUTFILE, IERR, NERR)
or
BAT_RNFI
TYPE
TRNFILE
INPFILE
OUTFILE
where:
Integer TYPE
Is the type of data file to be processed (input).

TYPE = 1, RESQ sequence data.
TYPE = 2, DRAW drawing coordinate data.
TYPE = 3, DYRE dynamics data.
TYPE = 4, MCRE machine impedance data.
TYPE = 5, ECDI dispatch data.
TYPE = 6, INLF dispatch data.
TYPE = 7, BKDY breaker duty data.
TYPE = 8, BKDY fault specification data.
TYPE = 9, ASCC fault control data.
TYPE = 10, GCAP capability curve data.
TYPE = 11, ACCC load throwover data.
TYPE = 12, ANSI fault specification data.
Character TRNFILE*260 Is the name of bus number translation input file (input).
Character INPFILE*260 Is the name of input data file (input).
Character OUTFILE*260 Is the name of output data file (blank for output to report window)
(input).
Integer IERR

IERR = 1, invalid TYPE value.
IERR = 2, error opening translation file.
IERR = 3, error opening input data file.
IERR = 4, error opening output data file.
Integer NERR
PSS/E-29
1-163
POWER FLOW APIS

RWCMAPI
1.133 RWCMAPI
This API executes activity RWCM. The API is invoked by the use of the statement:
RWCMAPI(OPT, OUT, OFILE, IERR, NERR)
or
BAT_RWCM
OPT
OUT
OFILE
where:
Integer OPT
Is the dc line/FACTS device option (input).

OPT = 0, ignore dc lines and FACTS devices.
OPT = 1, add powers to loads.
Integer OUT


Integer IERR

IERR = 1, invalid value of OPT.
IERR = 4, working case inconsistent with IEEE common format.
Integer NERR
1-164
PSS/E-29
POWER FLOW APIS

RWMANW
1.134 RWMANW
This API is used to write out machine parametric data from the working case in the form of a
Machine Impedance Data file. The API is invoked by the use of the statement:
RWMANW(SID, ALL, STATUS, OUT, OFILE, IERR)
or:
BAT_RWMA
SID
ALL STATUS(1)
STATUS(2)
STATUS(3)
OUT
OFILE
where:
Integer SID
Integer ALL

Integer STATUS(3)
Is an array of three elements. They are used to control output options. They are
as follows.
STATUS(1), include records for out-of-service machines.
STATUS(1) = 0, exclude them.
STATUS(1) = 1, include them.
STATUS(2), used when calculating P fractions.
STATUS(2) = 0, use PGEN.
STATUS(2) = 1, use MBASE.
STATUS(2) = 2, use PMAX.
STATUS(3), used when calculating Q fractions.
STATUS(3) = 0, use QGEN.
STATUS(3) = 1, use MBASE.
STATUS(3) = 2, use QMAX.
Integer OUT

Character OFILE*260 Is the output filename.

Integer IERR
PSS/E-29

IERR = 0, no error.
IERR = 4, unable to open OFILE.
1-165
POWER FLOW APIS

RWMMAPI
1.135 RWMMAPI
This API executes activity RWMM. The API is invoked by the use of the statement:
RWMMAPI(OUT, OFILE, IERR, NERR)
or
BAT_RWMM
Integer OUT
OUT
OFILE


Integer IERR

Integer NERR
1-166
PSS/E-29
POWER FLOW APIS

RWSQNW
1.136 RWSQNW
This API is used to write out the sequence data contained in the working case in the form of a
Sequence Data file. The API is invoked by the use of the statement:
RWSQNW(SID, ALL, STATUS, OUT, OFILE, IERR)
or:
BAT_RWSQ
OUT OFILE
SID
ALL
STATUS(1)
STATUS(2)
STATUS(3)
STATUS(4)
where:
Integer SID
Integer ALL

Integer STATUS(4)
Is an array of four elements. They are used to control output options. A value
STATUS(4), include subsystem ties.
Integer OUT


Integer IERR
PSS/E-29

IERR = 0, no error.
1-167
POWER FLOW APIS

SAVE_OPTION_SETTINGS_API
1.137 SAVE_OPTION_SETTINGS_API
This API is used to save the present values of the PSS/E program option settings in the file
"psse.opt".
CALL SAVE_OPTION_SETTINGS_API
or
BAT_SAVE_OPTION_SETTINGS
1-168
PSS/E-29
POWER FLOW APIS

SAVENW
1.138 SAVENW
This API is used to save a PSS/E Saved Case file. The API is invoked by the use of the statement:
SAVENW(SFILE, IERR)
or:
BAT_SAVE
SFILE
where:
Character SFILE*260
Is the PSS/E Saved Case. If SFILE is "*", SAVENW will attempt to save the
Saved Case file with the last name used. If none exists, SAVENW will return
an IERR value.
Integer IERR

IERR = 2, error writing to SFILE.
PSS/E-29
1-169
POWER FLOW APIS

SCALNW
1.139 SCALNW
This API is used to uniformly increase or decrease any or all of selected bus quantities for a selected
group of buses. The API is invoked by the use of the statement:
SCALNW(SID, ALL, APIOPT, TOTALS, MOTO, STATUS, SCALVAL, IERR)
or:
BAT_SCAL
SID ALL APIOPT STATUS(1) STATUS(2) STATUS(3)
STATUS(4) SCALVAL(1) SCALVAL(2) SCALVAL(3) SCALVAL(4)
SCALVAL(5) SCALVAL(6) SCALVAL(7)
where:
Integer SID
Integer ALL

Integer APIOPT

APIOPT = 1, initialize for scaling.
APIOPT = 2, perform the scaling.
Real TOTALS(11)
Is an array of eleven elements returned when APIOPT = 1. They are as

follows.
TOTALS(1), load Mvar total.
TOTALS(2), load MW total.
TOTALS(3), generation total.
TOTALS(4), shunt MW total.
TOTALS(5), reactor total.
TOTALS(6), capacitor total.
TOTALS(7), motor load total.
TOTALS(8), generator PMAX.
TOTALS(9), generator PMIN.
TOTALS(10), motor load PMIN.
TOTALS(11), motor load PMAX.
Integer MOTO
Is returned when APIOPT = 1.

MOTO = 0, no motors in the selected subsystem.
MOTO = 1, motors present in the selected subsystem.
1-170
PSS/E-29
POWER FLOW APIS

SCALNW
Integer STATUS(4)
Is an array of four elements. They are used to control scaling when

APIOPT = 2. They are as follows.
STATUS(1), method used to scale data.
STATUS(1) = 0, no scaling.
STATUS(1) = 1, specify new total powers.
STATUS(1) = 2, specify percent changes.
STATUS(2), used to enforce machine power limits.
STATUS(2) = 0, ignore machine power limits.
STATUS(2) = 1, enforce machine power limits.
STATUS(3), used to specify the scaling rule to be enforced when changing
the reactive power load.
STATUS(3) = 1, constant P/Q ratio.
STATUS(3) = 2, new total Q load.
STATUS(3) = 3, percent change.
STATUS(3) = 4, new power factor.
STATUS(4), is a special OPF bus type code flag for load scaling.
STATUS(4) = 1, only type 1 buses in subsystem.
STATUS(4) = 2, only type 2 and 3 buses in subsystem.
Real SCALVAL(7)
Is an array of seven elements used to scale the subsystem. Based on the value
of STATUS(1), these values are either total powers or percent changes.
SCALVAL(1), load MW total/percent.
SCALVAL(2), generation total/percent.
SCALVAL(3), shunt MW total/percent.
SCALVAL(4), reactor total/percent.
SCALVAL(5), capacitor total/percent.
SCALVAL(6), motor load total/percent.
SCALVAL(7), reactive load scaling parameter.
If STATUS(3) = 2, SCALVAL(7) = new total.
If STATUS(3) = 3, SCALVAL(7) = percent change.
If STATUS(3) = 4, SCALVAL(7) = new power factor.
PSS/E-29
1-171
POWER FLOW APIS

SCALNW
Integer IERR
1-172

IERR = 0, no error.
IERR = 4, generator/motor totals beyond limits.
PSS/E-29
POWER FLOW APIS

SCEQNW
1.140 SCEQNW
This API is used to construct network equivalents of the positive and zero sequence networks, and
calculates source impedances at equivalent source nodes for all three sequences in preparation for
the unbalanced fault analysis activities of PSS/E. The API is invoked by the use of the statement:
SCEQNW(SID, ALL, STATUS, THRESH, RFILE, SFILE, IERR)
or:
BAT_SCEQ
SID
ALL
STATUS
THRESH
RFILE
SFILE
where:
Integer SID

Integer ALL

Integer STATUS
Is used to determine whether transformer impedance correction is to be

applied to zero sequence lines.
STATUS = 1, apply correction.
STATUS = 0, do not apply correction.
Real THRESH
Is the branch threshold tolerance.
Character RFILE*260 Is the Raw Data file, not required.

Character SFILE*260
Is the Sequence Data file, not required.
Integer IERR

IERR = 3, not flat conditions or generators not converted.
IERR = 4, no buses being retained, none being equivalenced, or postequivalent case too big.
IERR = 5, error opening RFILE and/or SFILE.
PSS/E-29
1-173
POWER FLOW APIS

SCGRAPI
1.141 SCGRAPI
This API calculates fault solutions. Results may be programmatically accessed via the "fetch" routines SCGTXT, SCGBUS, SCGBRN, and SCG3WN.
Usage is:
call to SCGRAPI with APIOPT = 0;

multiple calls to "fetch" routines;
optionally, repeat of above steps for different fault and/or different prefault conditions;
final call to SCGRAPI with APIOPT = 1.

CALL SCGRAPI(SID, ALL, APIOPT, STATUS, IERR, NERR)
or
BAT_SCGR
SID
ALL
APIOPT
STATUS(1) . . . STATUS(8)
where:
Integer SID

Integer ALL
Is the "all" buses or selected subsystem flag for calculating results (input).
ALL = 0, only buses in subsystem SID.
ALL = 1, all buses in the working case.
Integer APIOPT
Is the mode of operation of SCGRAPI (input).

APIOPT = 0, do fault calculations and fill arrays used by fetch routines.
APIOPT = 1, deallocate arrays used by fetch routines.
Integer STATUS(8)
Is an array of eight elements specifying fault and output options (input).

STATUS(1), fault type.
STATUS(1) = 0, three-phase.
STATUS(1) = 1, line-to-ground.
STATUS(2), L-G fault output (ignored if STATUS(1)=0).
STATUS(2) = 0, A phase.
STATUS(2) = 1, 3 * I0.
STATUS(3), fault location.
STATUS(3) = >0, bus number of the subsystem bus to be faulted.
STATUS(4), flat conditions option.
STATUS(4) = 0, working case conditions.
STATUS(4) = 1, flat conditions.
1-174
PSS/E-29
POWER FLOW APIS

SCGRAPI
STATUS(5), double precision option.

STATUS(5) = 0, single precision.
STATUS(5) = 1, double precision.
STATUS(6), dc line and FACTS device option (ignored if
STATUS(4)=1).
STATUS(6) = 0, block.
STATUS(6) = 1, represent as load.
STATUS(7), transformer impedance correction option (ignored if
STATUS(1)=0 or STATUS(4)=1.
STATUS(7) = 0, do not apply to zero sequence.
STATUS(7) = 1, apply to zero sequence.
STATUS(8), branch results option.
STATUS(8) = 0, currents.
STATUS(8) = 1, apparent impedances.
Integer IERR

IERR = 3, specified faulted bus error.
IERR = 5, no sequence data in case.
Integer NERR
PSS/E-29
1-175
POWER FLOW APIS

SCMUAPI
1.142 SCMUAPI
This API executes activity SCMU. It must be called once with APIOPT set to 1, once for each of
the simultaneous faults to be applied with APIOPT set to 2, and once with APIOPT set to 3. The
CALL SCMUAPI(APIOPT, OPTIONS, RVAL, CKTARG, IERR, NERR)
or
BAT_SCMU
APIOPT
RVAL(5) CKTARG
RVAL(1) . . .
where:
Integer APIOPT
Is the mode of operation of SCMUAPI (input).

APIOPT = 1, initialize; automatically performs activity SEQD if the
sequence network setup option setting is enabled.
APIOPT = 2, specify an unbalance to be applied; must be called once for
each simultaneous unbalance to be imposed.
APIOPT = 3, solve in the presence of the specified unbalances and
terminate.
Integer OPTIONS(7)
Is an array of seven elements specifying options and input values to be

used in the current calculation phase of SCMUAPI; ignored when APIOPT
is 3 (input).
When APIOPT is 1, the first three elements of OPTIONS define options to
be used in the construction of the sequence admittance matrices. These
values are used only when the sequence network setup option is enabled,
and activity SEQD is to be automatically executed.
terms.
terms.
OPTIONS(3) = 0, do not apply to zero sequence transformer impedances.
OPTIONS(3) = 1, apply same factor used in the positive sequence to each
transformers zero sequence impedance.
1-176
PSS/E-29
POWER FLOW APIS

SCMUAPI
When APIOPT is 2, the first element of OPTIONS is used to define the

type of unbalance to be applied.
OPTIONS(1), unbalance type.
OPTIONS(1) = 1, first line-to-ground fault.
OPTIONS(1) = 2, second line-to-ground fault.
OPTIONS(1) = 3, first line-to-line or line-to-line-to-ground fault.
OPTIONS(1) = 4, second line-to-line or line-to-line-to-ground fault.
OPTIONS(1) = 5, one phase closed.
OPTIONS(1) = 6, two phases closed.
OPTIONS(1) = 7, three-phase fault (uses fault types 2 and 4).
OPTIONS(1) = 8, branch unbalance with one end opened.
OPTIONS(1) = 9, branch unbalance with both ends closed.
The remaining elements of OPTIONS are dependent on the value specified
for OPTIONS(1) and are described at the end of this section.
Real RVAL(5)
Is an array of five elements specifying input values used to define the current fault; ignored except when APIOPT is 2. The elements of RVAL are
dependent on the value specified for OPTIONS(1) and are described at the
end of this section (input).
Character CKTARG*2 Is the circuit identifier of branch to be faulted; ignored except when
APIOPT is 2 and OPTIONS(1) is 8 or 9 (input).
Integer IERR

IERR = 5, invalid APIOPT 1 call (already made; need APIOPT 2 or 3 call).
IERR = 6, invalid APIOPT 2 or 3 call (no APIOPT 1 call).
IERR = 7, invalid unbalance type.
IERR = 8, bus not found.
IERR = 9, invalid phase value.
IERR = 10, branch not found.
IERR = 11, invalid distance factor.
IERR = 12, invalid fault specification or application.
Integer NERR
PSS/E-29
1-177
POWER FLOW APIS

SCMUAPI
When APIOPT is 2 and OPTIONS(1) is 1 or 2, the following additional elements of OPTIONS

and RVAL are used.
Integer OPTIONS(7)

OPTIONS(3), faulted phase.
Real RVAL(5)
RVAL(1), resistance of the complex L-G fault impedance in pu.

RVAL(2), reactance of the complex L-G fault impedance in pu.
When APIOPT is 2 and OPTIONS(1) is 3 or 4, the following additional elements of OPTIONS

and RVAL are used.
Integer OPTIONS(7)

OPTIONS(3), excluded phase.
Real RVAL(5)
RVAL(1), resistance of the complex L-L fault impedance in pu.

RVAL(2), reactance of the complex L-L fault impedance in pu.
RVAL(3), resistance of the complex L-G fault impedance in pu.
RVAL(4), reactance of the complex L-G fault impedance in pu.
When APIOPT is 2 and OPTIONS(1) is 5, the following additional elements of OPTIONS and
RVAL are used.
Integer OPTIONS(7)
OPTIONS(2), one of the buses to be connected by the phase closed

unbalance.
OPTIONS(3), the other bus to be connected by the phase closed
unbalance.
OPTIONS(4), phase.
Real RVAL(5)
1-178
RVAL(1), resistance of the complex phase impedance in pu.

RVAL(2), reactance of the complex phase impedance in pu.
PSS/E-29
POWER FLOW APIS

SCMUAPI
RVAL are used.
Integer OPTIONS(7)
OPTIONS(2), one of the buses to be connected by the phase closed

unbalance.
OPTIONS(3), the other bus to be connected by the phase closed
unbalance.
OPTIONS(4), excluded phase.
Real RVAL(5)
RVAL(1), resistance of the complex phase impedance in pu.

RVAL(2), reactance of the complex phase impedance in pu.
RVAL are used.
Integer OPTIONS(7)
Real RVAL(5)
None.
RVAL are used.
Integer OPTIONS(7)
OPTIONS(2), one of the buses connected by the branch to be faulted.

OPTIONS(3), another bus connected by the branch to be faulted.
OPTIONS(4), third bus connected by the three-winding transformer to be
faulted, or zero for a two-terminal branch.
OPTIONS(5), type of in-line fault to be applied.
OPTIONS(5) = 1, line-to-ground.
OPTIONS(5) = 3, three-phase.
OPTIONS(6), faulted (if OPTIONS(5) is 1) or excluded (if OPTIONS(5)
is 2) phase.
OPTIONS(7), opened end bus (must be identical to one of OPTIONS(2),
OPTIONS(3), or, if it is non-zero, OPTIONS(4)).
PSS/E-29
1-179
POWER FLOW APIS

SCMUAPI
Real RVAL(5)
RVAL(1), resistance of the complex L-G (if OPTIONS(5) is 1) or L-L (if

OPTIONS(5) is 2).
OPTIONS(5) is 2).
RVAL(5), fault location from closed end bus in pu of total line length;
must be 1.0 if the branch is a transformer.
RVAL are used.
Integer OPTIONS(7)
OPTIONS(2), one of the buses connected by the branch to be faulted.

OPTIONS(3), the other bus connected by the branch to be faulted.
OPTIONS(4), type of in-line fault to be applied.
OPTIONS(4) = 3, three-phase.
OPTIONS(5), faulted (if OPTIONS(4) is 1) or excluded (if OPTIONS(4)
is 2) phase.
Real RVAL(5)
1-180
RVAL(1), resistance of the complex L-G (if OPTIONS(4) is 1) or L-L (if

OPTIONS(4) is 2).
OPTIONS(4) is 2).
RVAL(5), fault location from bus OPTIONS(2) in pu of total line length.
PSS/E-29
POWER FLOW APIS

SCOPAPI
1.143 SCOPAPI
This API tabulates fault solution output (activity SCOP). It must be referenced as follows:
Execution of activity SCMU, either interactively or via BAT_SCMU;

Followed by one reference of BAT_SCOP with APIOPT=1;
Followed by any number of references of BAT_SCOP with APIOPT=2;
Followed by one reference of BAT_SCOP with APIOPT=3.

CALL SCOPAPI(SID, ALL, UNITS, APIOPT, IERR, NERR)
or
BAT_SCOP
SID
ALL
UNITS
APIOPT
where:
Integer SID
Is a valid subsystem ID; used only when APIOPT = 2 and ALL = 0. Valid
subsystem IDs range from 0 to 3. A subsystem must have been previously
defined (input).
Integer ALL
Is the "all" buses or selected buses subsystem flag; used only when
APIOPT = 2 (input).
ALL = 0, process subsystem specified by SID.
Integer UNITS
Is the branch quantity output flag; used only when APIOPT = 2 (input).
UNITS = 1, currents.
UNITS = 2, apparent impedances.
UNITS = 3, apparent admittances.
Integer APIOPT
Is the mode of operation of SCOPAPI (input).

APIOPT = 1, initialize for short circuit output.
APIOPT = 2, produce output.
APIOPT = 3, post-processing clean up.
Integer IERR

IERR = 1, ALL or SID (invalid value or subsystem SID not defined) is in
error.
IERR = 2, UNITS is in error.
IERR = 4, no sequence data in case.
IERR = 5, initialization error.
Integer NERR
PSS/E-29
1-181
POWER FLOW APIS

SEQDAPI
1.144 SEQDAPI
This API executes activity SEQD. The API is invoked by the use of the statement:
CALL SEQDAPI(OPTIONS, IERR, NERR)
or
BAT_SEQD
OPTIONS(1)
OPTIONS(2)
OPTIONS(3)
where:
Integer OPTIONS(3)
Is an array of three elements specifying options to be used in constructing

the sequence matrices (input). The values are as follows:
terms.
terms.
OPTIONS(3) = 0, do not apply to zero sequence transformer impedances.
OPTIONS(3) = 1, apply same factor used in the positive sequence to each
transformers zero sequence impedance.
Integer IERR

Integer NERR
1-182
PSS/E-29
POWER FLOW APIS

SEQUENCE_NETWORK_SETUP_API
1.145 SEQUENCE_NETWORK_SETUP_API
This API is used to set the value of the fault analysis sequence network setup option setting to either
"off" or "on". The API is invoked by the use of the statement:
CALL SEQUENCE_NETWORK_SETUP_API(IVAL, IOCODE, IERR, NERR)
or
BAT_SEQUENCE_NETWORK_SETUP
IVAL
where:
Integer IVAL

IVAL = 0, SCMU assumes SEQD has already been executed.
IVAL = 1, SCMU always executes activity SEQD.
Integer IOCODE

Integer IERR

Integer NERR
PSS/E-29
1-183
POWER FLOW APIS

SHNTNW
1.146 SHNTNW
This API is used to tabulate fixed and/or switched bus shunt contained in the working case. The API
SHNTNW(SID, ALL, OPT, IERR)
or:
BAT_SHNT
SID
ALL
OPT
where:
Integer SID

Integer ALL

Integer OPT
Is used to select the type of bus shunts tabulated.

OPT = 1, all shunts.
OPT = 2, fixed shunts.
OPT = 3, switched shunts.
Integer IERR

1-184
PSS/E-29
POWER FLOW APIS

SHORT_CIRCUIT_COORDINATES_API
1.147 SHORT_CIRCUIT_COORDINATES_API
This API is used to set the value of the fault analysis output coordinates option setting to either
"rectangular" or "polar". The API is invoked by the use of the statement:
CALL SHORT_CIRCUIT_COORDINATES_API(IVAL, IOCODE, IERR, NERR)
or
BAT_SHORT_CIRCUIT_COORDINATES
IVAL
where:
Integer IVAL

IVAL = 0, rectangular.
IVAL = 1, polar.
Integer IOCODE

Integer IERR

Integer NERR
PSS/E-29
1-185
POWER FLOW APIS

SHORT_CIRCUIT_MODELING_API
1.148 SHORT_CIRCUIT_MODELING_API
This API is used to set the value of the fault analysis modeling option setting to either "normal threephase" or "center tapped two-phase". The API is invoked by the use of the statement:
CALL SHORT_CIRCUIT_MODELING_API(IVAL, IOCODE, IERR, NERR)
or
BAT_SHORT_CIRCUIT_MODELING
IVAL
where:
Integer IVAL

IVAL = 0, center tapped two-phase.
IVAL = 1, normal three-phase.
Integer IOCODE

Integer IERR

Integer NERR
1-186
PSS/E-29
POWER FLOW APIS

SHORT_CIRCUIT_UNITS_API
1.149 SHORT_CIRCUIT_UNITS_API
This API is used to set the value of the fault analysis output units option setting to either "pu" or
"physical". The API is invoked by the use of the statement:
CALL SHORT_CIRCUIT_UNITS_API(IVAL, IOCODE, IERR, NERR)
or
BAT_SHORT_CIRCUIT_UNITS
IVAL
where:
Integer IVAL

IVAL = 0, pu.
IVAL = 1, physical.
Integer IOCODE

Integer IERR

Integer NERR
PSS/E-29
1-187
POWER FLOW APIS

SHORT_CIRCUIT_WARNING_API
1.150 SHORT_CIRCUIT_WARNING_API
This API is used to set the value of the fault analysis warning option setting to either "on" or "off".
CALL SHORT_CIRCUIT_WARNING_API(IVAL, IOCODE, IERR, NERR)
or
BAT_SHORT_CIRCUIT_WARNING
IVAL
where:
Integer IVAL

IVAL = 0, disable printing of RESQ/TRSQ/solution warnings.
IVAL = 1, print RESQ/TRSQ/solution warnings.
Integer IOCODE

Integer IERR

Integer NERR
1-188
PSS/E-29
POWER FLOW APIS

SHOWAPI
1.151 SHOWAPI
This API executes activity SHOW. The API is invoked by the use of the statement:
CALL SHOWAPI(OPTION, FILE, IERR, NERR)
or
BAT_SHOW
OPTION
FILE
where:
Integer OPTION
Is the code for types of files to report (input).

OPTION = 0, file specified in FILE argument.
OPTION = 1, all ".sav" and ".snp" files.
OPTION = 2, all ".sav" files.
OPTION = 3, all ".snp" files.
Character FILE*260
Is the name of Save Case or Snapshot input file; only used if OPTION is 0
(input).
Integer IERR

IERR = 1, invalid OPTION value.
IERR = 2, FILE is blank when OPTION is 0.
Integer NERR
PSS/E-29
1-189
POWER FLOW APIS

SIZE_LEVEL_API
1.152 SIZE_LEVEL_API
This API is used to set the value of the PSS/E size level option setting to a multiple of 1,000 between
1,000 and 80,000. The API is invoked by the use of the statement:
CALL SIZE_LEVEL_API(IVAL, IOCODE, IERR, NERR)
or
BAT_SIZE_LEVEL
IVAL
where:
Integer IVAL
Is the value of the option setting between 1000 and 80000 (input if
IOCODE is 0 or BAT_ command, output if IOCODE is 1).
Integer IOCODE

Integer IERR

Integer NERR
1-190
PSS/E-29
POWER FLOW APIS

SIZEAPI
1.153 SIZEAPI
This API executes activity SIZE. The API is invoked by the use of the statement:
CALL SIZEAPI(IERR, NERR)
or
BAT_SIZE
where:
Integer IERR

Integer NERR
PSS/E-29
1-191
POWER FLOW APIS

SOLVAPI
1.154 SOLVAPI
This API executes activity SOLV. This API uses the default element specification as described in
SOLVAPI(OPTIONS, IERR, NERR)
or
BAT_SOLV
OPTIONS(5)
OPTIONS(1)
OPTIONS(6)
OPTIONS(2)
OPTIONS(3)
OPTIONS(4)
where:
Integer OPTIONS(6)
Is an array of six element specifying solution options (input). The values

are as follows:
interchange.
interchange.
OPTIONS(6) = 0, apply var limits.
OPTIONS(6) = 1, ignore var limits.
1-192
PSS/E-29
POWER FLOW APIS

SOLVAPI
Integer IERR

Integer NERR
PSS/E-29
1-193
POWER FLOW APIS

SPCBAPI
1.155 SPCBAPI
This API executes activity SPCB. The API is invoked by the use of the statement:
SPCBAPI(FROM, TO, CKT, OPTIONS, VALUES, IERR, NERR)
or
BAT_SPCB
OPTIONS(4)
FROM TO
VALUES(1)
CKT OPTIONS(1) OPTIONS(2) OPTIONS(3)

VALUES(2) VALUES(3) VALUES(4) VALUES(5)
where:
Integer FROM
Is the "from bus" of branch subjected to unbalance (input).
Integer TO
Is the "to bus" of branch subjected to unbalance (input).
Character CKT*2
Is the circuit identifier of branch subjected to unbalance (input).
Integer OPTIONS(4)
Is an array of four elements array specifying unbalance options (input).

OPTIONS(1), unbalance code.
OPTIONS(1) = 0, exit.
OPTIONS(1) = 1, one phase open.
OPTIONS(1) = 2, two phases open.
OPTIONS(1) = 3, in-line fault.
OPTIONS(1) = 4, one breaker open.
OPTIONS(1) = 5, no unbalance.
OPTIONS(2), path to ground code (used when OPTIONS(1) is 1 or 4).
OPTIONS(2) = 0, no path to ground.
OPTIONS(2) = 1, include a path to ground.
OPTIONS(3), type of in-line fault code (used when OPTIONS(1) is 3).
OPTIONS(3) = 2, line-to-line-to-ground.
OPTIONS(3) = 3, three phase.
OPTIONS(4), open end code (used when OPTIONS(1) is 4).
OPTIONS(4) = 0, breaker at bus TO is open.
OPTIONS(4) = 1, breaker at bus FROM is open.
Real VALUES(5)
1-194
Is an array of five elements specifying unbalance parameters (input).

VALUES(1), fault location as fraction of line from bus FROM;
0.0 < VALUES(1) < 1.0 (used when OPTIONS(1) is 1 or 4 and
OPTIONS(2) is 1; or when OPTIONS(1) is 3).
PSS/E-29
POWER FLOW APIS

SPCBAPI
VALUES(2) & (3), Rl-g and Xl-g (used when OPTIONS(1) is 1 or 4 and
OPTIONS(2) is 1; or when OPTIONS(1) is 3 and OPTIONS(3) is 1 or 2).
VALUES(4) & (5), Rl-l and Xl-l (used when OPTIONS(1) is 3 and
OPTIONS(3) is 2).
Integer IERR

IERR = 2, two phase option is enabled.
IERR = 3, bus not in case.
IERR = 4, unable to apply unbalance to branch specified.
IERR = 6, invalid VALUES(1) value.
Integer NERR
PSS/E-29
1-195
POWER FLOW APIS

SPILAPI
1.156 SPILAPI
This API executes activity SPIL. The API is invoked by the use of the statement:
CALL SPILAPI(OPTIONS, TOLS, LABELS, DFXFILE, PRTFILE, IERR, NERR)
or
BAT_SPIL
OPTIONS(1) . . . OPTIONS(16) TOLS(1) . . . TOLS(7)
LABELS(1) . . . LABELS(8) DFXFILE PRTFILE
where:
Integer OPTIONS(16) Is an array of sixteen elements specifying calculation and reporting options
OPTIONS(5) = 0, no.
OPTIONS(6) = 0, no.
OPTIONS(7) = 0, no.
OPTIONS(8) = 0, no.
1-196
PSS/E-29
POWER FLOW APIS

SPILAPI

OPTIONS(10), interchange limit output code.
OPTIONS(10) = 0, incremental transfer capability.
OPTIONS(10) = 1, total transfer capability.
OPTIONS(11), apply summary minimum distribution factor, TOLS(4), to
solution reports.
OPTIONS(14), summary table contingency descriptions.
OPTIONS(14) = 0, contingency labels.
OPTIONS(14) = 1, contingency events.
OPTIONS(14) = 2, both contingency labels and events.
OPTIONS(15), number of elements to include in flow tables.
OPTIONS(16), summary table maximum times for reporting the same
element.
Real TOLS(7)
Is an array of seven elements specifying tolerances and thresholds (input).

TOLS(3), summary table maximum import or export (>0.).
TOLS(4), summary table minimum distribution factor magnitude.
TOLS(5), minimum contingency case pre-shirt flow change.
TOLS(6), minimum contingency case distribution factor change.
Character LABELS*12 Is an array of eight elements specifying subsystem and interface labels
(input).
LABELS(2), opposing system label.
LABELS(3), interface label for optional interface limits summary table
(blank for none).
PSS/E-29
1-197
POWER FLOW APIS

SPILAPI

(blank for none).
(blank for none).
(blank for none.
(blank for none).
(blank for none).
Character PRTFILE*260 Is the name of Subsystem Participation Data input file; blank for none
(input).
Integer IERR

subsystems.
Integer NERR
1-198
PSS/E-29
POWER FLOW APIS

SPLTAPI
1.157 SPLTAPI
This API adds a bus to the working case and places a zero impedance line between bus BUS and
the new bus. No other equipment is connected to the new bus by this API. The API is invoked by
SPLTAPI(BUS, NEWNUM, NEWNAM, NEWKV, IERR, NERR)
or
BAT_SPLT
BUS
NEWNUM
NEWNAM
NEWKV
where:
Integer BUS
Is the number of the bus to be split (input).
Integer NEWNUM
Is the number to be assigned to the new bus (input).
Character NEWNAM*8Is the name to be assigned to the new bus (input).

Real NEWKV
Is the base voltage to be assigned to the new bus (input).
Integer IERR

IERR = 1, BUS not in working case.
IERR = 2, invalid NEWNUM value.
IERR = 3, bus NEWNUM already in working case.
IERR = 4, invalid NEWKV value.
IERR = 5, bus, branch, or branch ownership tables full.
Integer NERR
PSS/E-29
1-199
POWER FLOW APIS

SQEXNW
1.158 SQEXNW
This API is used to provide a tabulation of all fault analysis data pertaining to a selected bus. The
SQEXNW(SID, ALL, IERR)
or:
BAT_SQEX
SID
ALL
where:
Integer SID

Integer ALL

Integer IERR

1-200
PSS/E-29
POWER FLOW APIS

SQLINW
1.159 SQLINW
This API is used to tabulate the sequence data in a form suitable for problem data documentation.
SQLINW(SID, ALL, OPT, IERR)
or:
BAT_SQLI
SID
ALL
OPT
where:
Integer SID

Integer ALL

Integer OPT
Is type of sequence data to tabulate.

= 1, full listing
= 3, generator data
= 5, two-winding transformer data
= 7, switch shunt data
Integer IERR
PSS/E-29
= 2, bus data
= 4, branch data
= 6, mutual data

1-201
POWER FLOW APIS

STOPAPI
1.160 STOPAPI
This API executes activity STOP. The API is invoked by the use of the statement:
CALL STOPAPI(DELETE)
or
BAT_STOP
DELETE
where:
Integer DELETE
1-202
Is the delete working files flag (input).

DELETE = 0, keep working files.
DELETE = 1, delete working files.
PSS/E-29
POWER FLOW APIS

SUBSNW
1.161 SUBSNW
This API is used to summarize conditions in the working case by tabulating the conditions at each
swing system bus, conditions at each area slack area bus, number of components, generation/
load/shunt totals, and loss/line shunt/charging totals by voltage levels. The API is invoked by the
SUBSNW(SID, ALL, IERR)
or:
BAT_SUBS
SID
ALL
where:
Integer SID

Integer ALL

Integer IERR

PSS/E-29
1-203
POWER FLOW APIS

SWITCHED_SHUNT_ADJUSTMENT_API
1.162 SWITCHED_SHUNT_ADJUSTMENT_API
This API is used to set the value of the switched shunt adjustment option setting to either "disabled"
or "enabled". The API is invoked by the use of the statement:
CALL SWITCHED_SHUNT_ADJUSTMENT_API(IVAL, IOCODE, IERR, NERR)
or
BAT_SWITCHED_SHUNT_ADJUSTMENT
IVAL
where:
Integer IVAL

IVAL = 0, disabled.
IVAL = 1, enabled.
Integer IOCODE

Integer IERR

Integer NERR
1-204
PSS/E-29
POWER FLOW APIS

TAP_ADJUSTMENT_API
1.163 TAP_ADJUSTMENT_API
This API is used to set the value of the default tap adjustment option setting to either "disabled",
"stepping" or "direct". The API is invoked by the use of the statement:
CALL TAP_ADJUSTMENT_API(IVAL, IOCODE, IERR, NERR)
or
BAT_TAP_ADJUSTMENT
IVAL
where:
Integer IVAL

IVAL = 0, locked (i.e., tap adjustment is disabled).
IVAL = 1, tap adjustment using the stepping method enabled.
IVAL = 2, tap adjustment using the direct method enabled.
Integer IOCODE

Integer IERR

Integer NERR
PSS/E-29
1-205
POWER FLOW APIS

TFLGNW
1.164 TFLGNW
This API is used to either set or reset the flags for all automatically adjustable transformers contained within the selected subsystem. The API is invoked by the use of the statement:
TFLGNW(SID, ALL, OPT, IERR)
or:
BAT_TFLG
SID
ALL
OPT
where:
Integer SID

Integer ALL

Integer OPT
Is used to select the setting given to the transformers.

OPT = 0, disable.
OPT = 1, enable.
Integer IERR

1-206
PSS/E-29
POWER FLOW APIS

TIESNW
1.165 TIESNW
This API is used to tabulate the flows on all area tie lines, with tie flows grouped by area. The API
TIESNW(SID, ALL, IERR)
or:
BAT_TIES
SID
ALL
where:
Integer SID
Is a valid area subsystem ID. Valid subsystem IDs range from 0 to 3. An area
Integer ALL
Is the "all" areas or selected areas subsystem flag (input).

Integer IERR

PSS/E-29
1-207
POWER FLOW APIS

TIEZNW
1.166 TIEZNW
This API is used to tabulate the flows on all zone tie lines, with tie flows grouped by zone. The API
TIEZNW(SID, ALL, IERR)
or:
BAT_TIEZ
SID
ALL
where:
Integer SID
Is a valid zone subsystem ID. Valid subsystem IDs range from 0 to 3. A zone
Integer ALL
Is the "all" zones or selected zones subsystem flag (input).

Integer IERR

1-208
PSS/E-29
POWER FLOW APIS

TIMEAPI
1.167 TIMEAPI
This API executes activity TIME. The API is invoked by the use of the statement:
CALL TIMEAPI(INIT)
or
BAT_TIME
INIT
where:
Integer INIT
PSS/E-29
Is the initialize timers flag.

INIT = 0, do not initialize.
INIT = >0, initialize.
1-209
POWER FLOW APIS

TLSTNW
1.168 TLSTNW
This API is used tabulate those transformers in the working case whose off-nominal turns ratio or
phase shift angle may be adjusted by the power flow solution activities. The API is invoked by the
TLSTNW(SID, ALL, OPT, VREV, IERR)
or:
BAT_TLST
SID
ALL
OPT
VREV
where:
Integer SID

Integer ALL

Integer OPT
Is used to select the type of transformers tabulated.

OPT = 0, all.
OPT = 1, violations only.
Integer VREV
units.
Integer IERR

1-210
PSS/E-29
POWER FLOW APIS

TLTGAPI
1.169 TLTGAPI
This API executes activity TLTG. The API is invoked by the use of the statement:
CALL TLTGAPI(OPTIONS, TOLS, LABELS, DFXFILE, IERR, NERR)
or
BAT_TLTG
LABELS(1) . . . LABELS(8) DFXFILE
TOLS(1) . . . TOLS(7)
where:
Integer OPTIONS(17) Is an array of seventeen elements specifying calculation and reporting
options (input). The values are as follows:
OPTIONS(5), code for the treatment of base case line flow constraints in
contingency cases.
OPTIONS(5) = 0, ignore.
OPTIONS(6) = 0, no.
OPTIONS(7) = 0, no.
OPTIONS(8) = 0, no.
PSS/E-29
1-211
POWER FLOW APIS

TLTGAPI

OPTIONS(9) = 0, no.
OPTIONS(11), interchange limit output code.
OPTIONS(11) = 0, incremental transfer capability.
OPTIONS(11) = 1, total transfer capability.
OPTIONS(12), apply summary minimum distribution factor, TOLS(4), to
solution reports.
OPTIONS(15), summary table contingency descriptions.
OPTIONS(15) = 0, contingency labels.
OPTIONS(15) = 1, contingency events.
OPTIONS(15) = 2, both contingency labels and events.
OPTIONS(16), number of elements to include in flow tables.
OPTIONS(17), summary table maximum times for reporting the same
element.
Real TOLS(7)
1-212
Is an array of seven elements specifying tolerances and thresholds (input).

TOLS(3), summary table maximum import or export (>0.).
TOLS(4), summary table minimum distribution factor magnitude.
TOLS(5), minimum contingency case pre-shirt flow change.
TOLS(6), minimum contingency case distribution factor change.
PSS/E-29
POWER FLOW APIS

TLTGAPI
Character LABELS*1
Is an array of eight elements specifying subsystem and interface labels

(input).
LABELS(2), opposing system label.
(blank for none).
(blank for none).
(blank for none).
(blank for none).
(blank for none).
(blank for none).
Integer IERR

IERR = 5, subroutine GETLOS error (generators are converted or
subsystems.
Integer NERR
PSS/E-29
1-213
POWER FLOW APIS

TPCHNW
1.170 TPCHNW
This API is used perform checks on the adjustment data associated with voltage or flow controlling
transformers. The API is invoked by the use of the statement:
TPCHNW(SID, ALL, APIOPT, OPT, STATUS, THRSH, TTYP, NTRN, IERR)
or:
BAT_TPCH
THRSH(2)
SID
ALL
APIOPT
OPT STATUS(1)
STATUS(2)
THRSH(1)
where:
Integer SID

Integer ALL

Integer APIOPT

APIOPT = 1, initialize for check and adjustment.
APIOPT = 2, check transformers.
APIOPT = 3, perform adjustment.
APIOPT = 4, postprocessing after adjustment.
Integer OPT
Is used to select the type of adjustment.

= 1, tap step = 0. (V/Mvar)
= 3, tap step > maximum (V/ Mvar)
= 5, voltage band < minimum (V)
= 8, flow band < minimum (MW/Mvar)
Integer STATUS(2)
= 2, 0. < step < minimum (V/ Mvar)

= 4, voltage band < 2*step (V)
= 6, voltage band > maximum
= 9, flow band > maximum
(MW/Mvar)
Is a two-element array.
STATUS(1), modify steps or voltage bands, when OPT = 4.
STATUS(1) = 1, modify steps.
STATUS(1) = 2, modify voltage bands.
STATUS(2), used to indicate which transformers to change where OPTs
1, 2, 3, 8 or 9.
STATUS(2) = 0, change both types.
STATUS(2) = 1, change voltage controlling types when OPTs 1, 2 or 3.
STATUS(2) = 2, change Mvar controlling types change MW controlling
types when OPT = 8 or 9.
1-214
PSS/E-29
POWER FLOW APIS

TPCHNW
Real THRSH(2)
Is a two-element array. The values are as follows.

THRSH(1), threshold to use in initial test.
THRSH(2), new tap step, voltage band, or flow band.
If OPT 1->3, THRSH(2) is the new tap step.
If OPT 5->6, THRSH(2) is the new voltage band.
If OPT 8->9, THRSH(2) is the new flow band.
Logical TTYP
Is returned when APIOPT = 2 or 3 and is TRUE if both voltage and Mvar

controlling transformers were found.
Integer NTRN
Is returned when APIOPT = 2 or 3 and is the number of transformers that

need adjustment under the adjustment type indicated by OPT.
Integer IERR

IERR = 4, bad THRSH(1) when APIOPT = 2 or bad THRSH(2) when
APIOPT = 3.
IERR = 5, no controlling transformers.
PSS/E-29
1-215
POWER FLOW APIS

TRANSMISSION_LINE_UNITS_API
1.171 TRANSMISSION_LINE_UNITS_API
This API is used to set the value of the transmission line units option setting to either "pu" or
"ohms". The API is invoked by the use of the statement:
CALL TRANSMISSION_LINE_UNIT_API(IVAL, IOCODE, IERR, NERR)
or
BAT_TRANSMISSION_LINE_UNIT
IVAL
where:
Integer IVAL

IVAL = 0, pu.
IVAL = 1, ohms/microfarads.
Integer IOCODE

Integer IERR

Integer NERR
1-216
PSS/E-29
POWER FLOW APIS

TREEAPI
1.172 TREEAPI
This API executes activity TREE. Following each successful call, it returns BUSES as the number
of buses in a swingless island (0 for no more swingless islands). Once a BUSES value of 0 is
returned, no further calls are needed.
The API must be called once with APIOPT set to 1. If BUSES is returned as 0 (i.e., there are no
swingless islands), no further calls are needed. Otherwise, if BUSES is greater than zero, it must be
called one or more times with APIOPT set to 2 and OPTION set to indicate the disposition of the
current swingless island. APIOPT 2 calls are required until either BUSES is returned as zero or an
APIOPT 2 call is made with OPTION set to 1.
CALL TREEAPI(APIOPT, OPTION, BUSES, IERR, NERR)
or
BAT_TREE
APIOPT
OPTION
where:
Integer APIOPT
Is the mode of operation of TREEAPI (input).

APIOPT = 1, initialize and check for the presence of a swingless island.
APIOPT = 2, process previously detected island as dictated by OPTION;
then check for the presence of another swingless island.
Integer OPTION
Is the option for the handling of previously detected swingless island;

ignored when APIOPT is 1 (input).
OPTION = <0, leave this island alone and terminate activity TREE.
OPTION = 0, leave this island alone and check for another swingless
island.
OPTION = >0, disconnect this island, then check for another swingless
island.
Integer BUSES
Is the number of buses in this swingless island; 0 if no more swingless

islands (output).
Integer IERR

IERR = 3, invalid APIOPT 1 call (already made; need APIOPT 2 call).
IERR = 4, invalid APIOPT 2 call (no APIOPT 1 call).
Integer NERR
PSS/E-29
1-217
POWER FLOW APIS

TYSLAPI
1.173 TYSLAPI
This API executes activity TYSL. The API is invoked by the use of the statement:
TYSLAPI(OPT, IERR, NERR)
or
BAT_TYSL
OPT
where:
Integer OPT
Is the flat start flag (input).

OPT = 0, use present voltage vector as starting point.
OPT = 1, "flat start".
Integer IERR

IERR = 1, invalid OPT value.
IERR = 2, generators are not "converted".
IERR = 3, network is not ordered.
IERR = 4, error reading factored matrix file (usually implies matrix is not
factorized).
Integer NERR
1-218
PSS/E-29
POWER FLOW APIS

USERAPI
1.174 USERAPI
This API executes activity USER. The API is invoked by the use of the statement:
CALL USERAPI
or
BAT_USER
PSS/E-29
1-219
POWER FLOW APIS

VCHKNW
1.175 VCHKNW
This API is used to tabulate those buses whose voltage magnitude is outside a specified range. The
VCHKNW(SID, ALL, VLO, VHI, IERR)
or:
BAT_VCHK
SID
ALL
VLO
VHI
where:
Integer SID

Integer ALL

Real VLO
Is the VMIN of the voltage band.
Real VHI
Is the VMAX of the voltage band.
Integer IERR

IERR = 2, either VLO or VHI is in error.
1-220
PSS/E-29
POWER FLOW APIS

VOLTAGE_INPUT_API
1.176 VOLTAGE_INPUT_API
This API is used to set the value of the voltage input option setting to either "pu" or "kV". The API
CALL VOLTAGE_INPUT_API(IVAL, IOCODE, IERR, NERR)
or
BAT_VOLTAGE_INPUT_UNIT
IVAL
where:
Integer IVAL

IVAL = 0, pu.
IVAL = 1, kV.
Integer IOCODE

Integer IERR

Integer NERR
PSS/E-29
1-221
POWER FLOW APIS

VOLTAGE_OUTPUT_API
1.177 VOLTAGE_OUTPUT_API
This API is used to set the value of the voltage output option setting to either "pu" or "kV". The API
CALL VOLTAGE_OUTPUT_API(IVAL, IOCODE, IERR, NERR)
or
BAT_VOLTAGE_OUTPUT_UNIT
IVAL
where:
Integer IVAL

IVAL = 0, pu.
IVAL = 1, kV.
Integer IOCODE

Integer IERR

Integer NERR
1-222
PSS/E-29
POWER FLOW APIS

ZONENW
1.178 ZONENW
This API is used to provide a tabulation by zones of the zone totals. The API is invoked by the use
of the statement:
ZONENW(SID, ALL, IERR)
or:
BAT_ZONE
SID
ALL
where:
Integer SID

Integer ALL
Is the "all" zones or selected subsystem flag (input).

Integer IERR

PSS/E-29
1-223
POWER FLOW APIS

ZONMNW
1.179 ZONMNW
This API is used to reassign the buses and loads in a selected subsystem of the working case from
their original zone to a designated zone. The API is invoked by the use of the statement:
ZONMNW(SID, ALL, STATUS, IZNEW, IERR)
or:
BAT_ZONM
SID
ALL
STATUS(1)
STATUS(2)
IANEW
where:
Integer SID

Integer ALL

Integer STATUS(2)
Is an array of two elements. The values are as follows.

STATUS(1) = 1, change bus zones to IZNEW; otherwise = 0.
STATUS(2) = 1, change load zones to IZNEW; otherwise = 0.
Integer IZNEW
Is the new zone to assign the selected buses to. IZNEW must be between 1 and
ZONES.
Integer IERR

IERR = 3, IZNEW not between 1 and ZONES.
1-224
PSS/E-29
CHAPTER
2
LOAD FLOW DATA CHANGING APIS
To specify the "default" value for a particular array element when calling the XXX_XXX_API subroutine, set the INTGAR array elements to the parameter BIGINT and REALAR array elements to
the parameter BIGREL, which is defined in the MODULE PARAM4; when entering the
BAT_XXX_XXX_DATA command, use FORTRAN free format input conventions (i.e., consecutive commas).
2.1 Area Data

AREA_API(I, INTGAR, REALAR, NAMEAR, IERR, NERR)
or
BAT_AREA_DATA
INTGAR(1)
REALAR(1)
REALAR(2)
NAMEAR
where:
Integer I
Is the area number.
Integer INTGAR(1)
Is an array of one element. The values are as follows:

INTGAR(1), area slack bus number.
Real REALAR(2)

REALAR(1), desired area interchange.
REALAR(2), desired interchange tolerance.
Character NAMEAR*8 Is the area name.

Integer IERR

IERR = >0, errors occurred.
IERR = 1, invalid area number.
PSS/E-29
2-1

Area Data
IERR = -1, warnings one or more of:

Area slack bus not found.
Slack bus is not in this area.
No generator on slack bus.
Slack bus is not type two or three.
Type 3 bus in area but it is not the area slack bus.
No equipment assigned to area.
Integer NERR
2-2
The number of entries in PBUF02 containing error messages.
PSS/E-29

Owner Data
2.2 Owner Data

OWNER_API(I, NAMEAR, IERR, NERR)
or
BAT_OWNER_DATA
NAMEAR
where:
Integer I
Is the owner number.
Character NAMEAR*8 Is the owner name.

Integer IERR

IERR = 0, no errors occurred.
IERR = 1, invalid owner number.
IERR = -1, warnings:
No equipment assigned to owner.
Integer NERR
PSS/E-29
2-3

Zone Data
2.3 Zone Data

ZONE_API(I, NAMEAR, IERR, NERR)
or
BAT_ZONE_DATA
NAMEAR
where:
Integer I
Is the zone number.
Character NAMEAR*8 Is the zone name.

Integer IERR

IERR = 1, invalid zone number.
No equipment assigned to zone.
Integer NERR
2-4
PSS/E-29

Bus Data
2.4 Bus Data

BUS_API(IBUS, INTGAR, REALAR, NAMEAR, IERR, NERR)
or
BAT_BUS_DATA
IBUS
INTGAR(1)...INTGAR(4)
REALAR(1)...REALAR(5)
NAMEAR
where:
Integer IBUS
Is the bus number.
Integer INTGAR(4)
Is an array of four elements. The values are as follows:

INTGAR(1), bus type code (see Program Operation Manual,
Section 4.1.1.2, IDE).
INTGAR(2), area number.
INTGAR(3), zone number.
INTGAR(4), owner number.
Integer REALAR(5)
Is an array of five elements. The values are as follows:

REALAR(1), fixed shunt admittance real part.
REALAR(2), fixed shunt admittance reactive part.
REALAR(3), bus base voltage in kV.
REALAR(4), bus voltage magnitude.
REALAR(5), bus voltage phase angle.
Character NAMEAR*8 Is the bus name.

Integer IERR

IERR = 1, invalid bus number.
IERR = 2, bus table full.
IERR = 3, working case not initialized.
Invalid base voltage.
Invalid bus type code.
Invalid area, zone or owner number.
New area number but bus is area swing for its old area.
Bus is type 3 but is not the swing for its area.
Integer NERR
PSS/E-29

2-5

Non-Transformer Branch Data
2.5 Non-Transformer Branch Data

BRANCH_API(IARG, JARG, CKT, INTGAR, REALAR, IERR, NERR)
or
BAT_BRANCH_DATA
IARG
JARG
CKT
where:
Integer IARG
Is the bus number of "from" bus.
Integer JARG
Is the bus number of "to" bus.
Character CKT*2
Is the circuit identifier.
Integer INTGAR(6)
Is an array of six elements. The values are as follows:

INTGAR(1), branch status (see Program Operation Manual,
Section 4.1.1.5, ST).
INTGAR(2), metered end bus number (IARG or JARG).
INTGAR(3), first owner number.
INTGAR(4), second owner number.
INTGAR(5), third owner number.
INTGAR(6), fourth owner number.
Integer REALAR(15)
Is an array of fifteen elements. The values are as follows:

REALAR(1), nominal branch resistance.
REALAR(2), nominal branch reactance.
REALAR(3), total line charging.
REALAR(4), rating set A line rating.
REALAR(5), rating set B line rating.
REALAR(6), rating set C line rating.
REALAR(7), real line shunt at bus IARG end.
REALAR(8), reactive line shunt at bus IARG end.
REALAR(9), real line shunt at bus JARG end.
REALAR(10), reactive line shunt at bus JARG end.
REALAR(11), line length.
REALAR(12), first owner fraction.
REALAR(13), second owner fraction.
REALAR(14), third owner fraction.
REALAR(15), fourth owner fraction.
2-6
PSS/E-29

Non-Transformer Branch Data
Integer IERR

IERR = 2, circuit identifier is more than two characters.
IERR = 4, branch from a bus to itself.
IERR = 5, blank circuit identifier.
IERR = 6, circuit identifier may not start with&.
IERR = 7, branch table full.
IERR = 8, branch ownership table full.
Line length may not be negative.
Invalid metered end bus.
Invalid branch status.
No ownership data specified.
Invalid owner number.
Invalid ownership factor.
Branch is no longer treated as a zero impedance line.
Zero impedance line table full.
Multi-section line grouping deleted.
Branch ownership table full.
Integer NERR
PSS/E-29
2-7

Two-Winding Transformer Data
2.6 Two-Winding Transformer Data

TWO_WINDING_API(IARG, JARG, CKT, INTGAR, REALAR, NAMEAR, IERR,
NERR)
or
BAT_TWO_WINDING_DATA, IARG, JARG, CKT, INTGAR(1)...INTGAR(15),
REALAR(1)...REALAR(23), NAMEAR
Integer IARG
Integer JARG
Character CKT*2
Integer INTGAR(15)

Section 4.1.1.6, STAT).
INTGAR(2), metered end bus external number (IARG or JARG).
INTGAR(7), number of tap positions.
INTGAR(8), impedance correction table number.
INTGAR(9), winding one side bus external number (IARG or JARG).
INTGAR(10), controlled bus number.
INTGAR(11), negative for controlled bus on winding one side.
INTGAR(12), adjustment control mode flag (-4 through +4).
INTGAR(13), winding data I/O code.
INTGAR(14), impedance data I/O code.
INTGAR(15), magnetizing admittance data I/O code.
Integer REALAR(25)
Is an array of 25 elements. The values are as follows:

REALAR(1), nominal transformer resistance.
REALAR(2), nominal transformer reactance.
REALAR(3), primary winding base MVA.
REALAR(4), primary winding ratio/voltage.
REALAR(5), primary winding nominal voltage.
REALAR(6), primary winding phase shift angle.
REALAR(7), secondary winding ratio/voltage.
REALAR(8), secondary winding nominal voltage.
2-8
PSS/E-29

REALAR(9), rating set A line rating.

REALAR(10), rating set B line rating.
REALAR(11), rating set C line rating.
REALAR(16), magnetizing conductance.
REALAR(17), magnetizing susceptance.
REALAR(18), primary winding ratio/angle high limit.
REALAR(19), primary winding ratio/angle low limit.
REALAR(20), voltage or flow upper limit.
REALAR(21), voltage or flow lower limit.
REALAR(22), load drop compensating resistance.
REALAR(23), load drop compensating reactance.
REALAR(24), actual transformer resistance (output only).
REALAR(25), actual transformer reactance (output only).
Character NAMEAR*8 Is the transformer name.
Integer IERR

IERR = 2, circuit ID is more than two characters.
IERR = 3, branch is not a transformer.
IERR = 6, circuit identifier may not start with &.
IERR = 7, branch table full.
IERR = 8, branch ownership table full.
IERR = 9, transformer table full.
IERR = 10, CW, CZ and/or CM >1 but no base voltage at one or both
buses.
IERR = 11, invalid CW, CZ and/or CM value.
PSS/E-29
2-9

Integer NERR
2-10

Invalid winding one side bus number.
Controlled bus not found.
Controlled side flag conflict when winding one or two side bus.
Invalid control mode flag.
Invalid impedance correction table number.
Invalid number of tap positions.
Winding nominal voltage is negative.
Winding bus base and nominal voltages differ by a large amount.
Negative or zero winding voltage or tap ratio.
Winding voltage and bus base voltage differ by a large amount.
Tap ratio less than 0.8 or greater than 1.2.
RMAX and nominal voltage differ by a large amount.
RMAX greater than 1.2.
RMIN and nominal voltage differ by a large amount.
RMIN less than 0.8.
RMAX less than RMIN.
VMAX less than VMIN.
Phase shift angle normalized between -180 and 180.
Winding base MVA is zero or negative.
MAG1 too big relative to MAG2 at winding base MVA.
Loss to big relative to |z| at winding base MVA.
Branch ownership table full.
PSS/E-29

Three-Winding Transformer Data
2.7 Three-Winding Transformer Data

This API is used to create or modify a three-winding transformer in the working case. The API is
THREE_WINDING_API(IARG, JARG, KARG, CKT, INTGAR, REALAR, NAMEAR,
IERR, NERR)
or:
BAT_THREE_WINDING_DATA
IARG
JARG
KARG
CKT
NAMEAR
where:
Integer IARG
Is the bus number of one of the buses.
Integer JARG
Is the bus number of another of the buses.
Integer KARG
Character CKT*2
Is the transformer circuit identifier.
Integer INTGAR(17)
Is an array of seventeen elements. The values are as follows:

INTGAR(5), number of tap positions.
INTGAR(6), impedance correction table number.
INTGAR(7), controlled bus number.
INTGAR(8), negative for controlled bus on winding one side.
INTGAR(9), adjustment control mode flag (-4 through +4).
INTGAR(10), winding data I/O code.
INTGAR(11), impedance data I/O code.
INTGAR(12), magnetizing admittance data I/O code.
INTGAR(14), non-metered end bus number.
INTGAR(15), winding one side bus number (IARG, JARG or KARG).
INTGAR(16), winding two side bus number (IARG, JARG or KARG).
INTGAR(17), winding three side bus number (IARG, JARG or KARG).
Real REALAR(53)
Is an array of 53 elements. The values are as follows:

REALAR(1), nominal bus one to two transformer resistance.
REALAR(2), nominal bus one to two transformer reactance.
PSS/E-29
2-11

REALAR(3), nominal bus one to three transformer resistance.

REALAR(4), nominal bus one to three transformer reactance.
REALAR(5), bus two to three transformer resistance.
REALAR(6), bus two to three transformer reactance.
REALAR(7), winding one base MVA.
REALAR(8), winding two base MVA.
REALAR(9), winding three base MVA.
REALAR(10), magnetizing conductance.
REALAR(11), magnetizing susceptance.
REALAR(12), winding one ratio or voltage.
REALAR(13), winding one nominal voltage.
REALAR(14), winding one-phase shift angle.
REALAR(15), winding one rating set A line rating.
REALAR(16), winding one rating set B line rating.
REALAR(17), winding one rating set C line rating.
REALAR(18), winding two ratio or voltage.
REALAR(19), winding two nominal voltage.
REALAR(20), winding two-phase shift angle.
REALAR(21), winding two rating set a line rating.
REALAR(22), winding two rating set B line rating.
REALAR(23), winding two rating set C line rating.
REALAR(24), winding three ratio or voltage.
REALAR(25), winding three nominal voltage.
REALAR(26), winding three-phase shift angle.
REALAR(27), winding three rating set A line rating.
REALAR(28), winding three rating set B line rating.
REALAR(29), winding three rating set C line rating.
REALAR(34), winding one ratio/angle high limit.
REALAR(35), winding one ratio/angle low limit.
REALAR(36), voltage or flow upper limit.
REALAR(37), voltage or flow lower limit.
REALAR(38), load drop compensating resistance.
REALAR(39), load drop compensating reactance.
REALAR(40), star bus voltage magnitude.
REALAR(41), star bus voltage angle.
2-12
PSS/E-29

REALAR(42), actual bus one to two resistance (output only).

REALAR(43), actual bus one to two reactance (output only).
REALAR(44), actual bus one to three resistance (output only).
REALAR(45), actual bus one to three reactance (output only).
REALAR(46), nominal winding one resistance (output only).
REALAR(47), nominal winding one reactance (output only).
REALAR(48), nominal winding two resistance (output only).
REALAR(49), nominal winding two reactance (output only).
REALAR(50), nominal winding three resistance (output only).
REALAR(51), nominal winding three reactance (output only).
REALAR(52), actual winding one resistance (output only).
REALAR(53), actual winding one reactance (output only).
Character NAMEAR*8 Is the transformer name.
Integer IERR

IERR = 3, invalid CW, CZ and/or CM value.
IERR = 4, CW, CZ and/or CM >1 but no base voltage at one or more buses.
IERR = 5, three different buses must be specified.
IERR = 7, circuit identifier may not start with &.
IERR = 8, three-winding transformer table full.
IERR = 9, bus table full.
IERR = 10, not enough branch table entries available.
IERR = 11, not enough room in two winding transformer table.
IERR = 12, not enough room in branch ownership table.
Invalid set of winding buses.
Invalid transformer status.
Invalid non-metered end bus.
Controlled bus not found.
Winding side buses interchanged.
Loss too big relative to |z| at winding base MVA.
Any two-winding transformer warnings.
Integer NERR
PSS/E-29
Is the number of entries in PBUF02 containing error messages.
2-13

Load Data
2.8 Load Data

LOAD_API(IARG,LDID,INTGAR,REALAR,IERR,NERR)
or
BAT_LOAD_DATA
IARG
LDID
where:
Integer IARG
Is the external bus number.
Character LDID*2
Is the load identifier.
Integer INTGAR(4)

INTGAR(1), load status (see Program Operation Manual, Section 4.1.1.3,
STATUS).
Integer REALAR(6)

REALAR(1), constant power real load.
REALAR(2), constant power reactive load.
REALAR(3), constant current real load.
REALAR(4), constant current reactive load.
REALAR(5), constant admittance real load.
REALAR(6), constant admittance reactive load.
Integer IERR

IERR = 2, load identifier is more than two characters.
IERR = 3, blank load identifier is invalid.
IERR = 4, load table full.
Invalid load status.
Invalid area, zone or owner number.
Integer NERR
2-14
PSS/E-29

Plant Data
2.9 Plant Data

PLANT_API(IARG, INTGAR, REALAR, IERR, NERR)
or
BAT_PLANT_DATA
IARG
INTGAR(1)
REALAR(1)
REALAR(2)
where:
Integer IARG
Is the bus number.
Integer INTGAR(1)

INTGAR(1), remote bus number.
Integer REALAR(2)

REALAR(1), scheduled voltage magnitude.
REALAR(2), percent of contributed vars.
Integer IERR

IERR = 2, plant table full.
Remote bus not found.
Remote bus type code is not 1 or 2.
Plant specified as remotely regulating itself.
RMPCT is not positive.
Invalid scheduled voltage.
Integer NERR
PSS/E-29
2-15

Machine Data
2.10 Machine Data

MACHINE_API(IARG, MCID, INTGAR, REALAR, IERR, NERR)
or
BAT_MACHINE_DATA
IARG
MCID
where:
Integer IARG
Character MCID*2
Is the machine identifier.
Integer INTGAR(5)

INTGAR(1), machine status (see Program Operation Manual,
Integer REALAR(16)
Is an array of sixteen elements. The values are as follows:

REALAR(1), machine real power output.
REALAR(2), machine reactive power output.
REALAR(3), machine reactive power upper limit.
REALAR(4), machine reactive power lower limit.
REALAR(5), machine real power upper limit.
REALAR(6), machine real power lower limit.
REALAR(7), machine MVA base.
REALAR(8), machine resistance.
REALAR(9), machine reactance.
REALAR(10), step up transformer resistance.
REALAR(11), step up transformer reactance.
REALAR(12), step up transformer tap ratio.
2-16
PSS/E-29

Machine Data
Integer IERR

IERR = 2, machine identifier is more than two characters.
IERR = 3, no plant data at bus.
IERR = 4, blank machine identifier is invalid.
IERR = 5, machine table full.
IERR = 6, machine ownership table full.
Invalid machine status.
Invalid ZSORCE: (0. 0.).
QMAX less than QMIN.
PMAX less than PMIN.
MBASE is not positive.
No ownership data.
Integer NERR
PSS/E-29
2-17

FACTS Device Data
2.11 FACTS Device Data

FACTS_API(KM, INTGAR, REALAR, IERR, NERR)
or
BAT_FACTS_DATA
KM
where:
Integer KM
Is the FACTS control device number (must be positive).
Integer INTGAR(4)

INTGAR(1), sending end bus number.
INTGAR(2), terminal end bus number (0 for STATCON).
INTGAR(3), control mode (see Program Operation Manual,
Section 4.1.1.6, MODE).
Integer REALAR(16)
Is an array of sixteen elements. The values are as follows:

REALAR(1), desired real power at terminal bus.
REALAR(2), desired reactive power at terminal bus.
REALAR(3), sending bus voltage setpoint.
REALAR(4), sending end maximum shunt current (MVA at rated
voltage).
REALAR(5), maximum bridge real power transfer.
REALAR(6), minimum terminal bus voltage magnitude.
REALAR(7), maximum terminal bus voltage magnitude.
REALAR(8), maximum series voltage magnitude.
REALAR(9), maximum series current (MVA at rated voltage).
REALAR(10), pu reactance of temporary series element.
REALAR(11), if mode=3, real, imag of constant Z; if mode=4.
REALAR(12), magnitude, angle of constant V; otherwise ignored.
REALAR(13), real of present effective series Z (output only).
REALAR(14), imag of present effective series Z (output only).
REALAR(15), magnitude of present series voltage (output only).
REALAR(16), angle of present series voltage (output only).
2-18
PSS/E-29

FACTS Device Data
Integer IERR

IERR = 1, invalid facts device number.
IERR = 3, bus not found or no sending end bus specified.
IERR = 4, same bus specified for sending and terminal buses.
Invalid control mode.
Sending bus voltage setpoint must be positive.
Terminal bus voltage limit must be positive.
VTMX is less than VTMN.
Series voltage limit must be positive.
Shunt current limit must not be negative.
Bridge real power transfer limit must not be negative.
Series current limit must not be negative.
Series reactance must be positive.
Impedance setpoint reactance must not be 0.
Bus is dummy bus of a multi-section line.
Multi-section line deleted.
Integer NERR
PSS/E-29
2-19

Two-Terminal dc Line Link Data
2.12 Two-Terminal dc Line Link Data

TWO_TERMINAL_DC_LINE_API(NDC, INTGAR, REALAR, METRAR, IERR, NERR)
or
BAT_TWO_TERMINAL_DC_LINE_DATA
NDC
METRAR
INTGAR(1)
INTGAR(2)
where:
Integer NDC
Is the dc line number (must be positive).
Integer INTGAR(2)
Is an array of two element. The values are as follows:

Section 4.1.1.8, MDC).
INTGAR(2), CCC Newton solution iteration limit.
Integer REALAR(9)
Is an array of nine elements. The values are as follows:

REALAR(1), scheduled current (amps) or power (MW) demand.
REALAR(2), scheduled dc voltage (kV).
REALAR(3), mode switch dc voltage (kV).
REALAR(4), margin (pu, > 0).
REALAR(5), dc line resistance.
REALAR(6), compounding resistance.
REALAR(7), minimum dc voltage (kV).
REALAR(8), CCC Newton solution acceleration.
REALAR(9), dc line current (amps) (output only).
Character METRAR*1 Is the metered end flag: R or I.

Integer IERR

IERR = 3, metrar is more than one character.
Invalid line resistance.
Invalid compounding resistance.
Compounding resistance exceeds line resistance.
2-20
PSS/E-29

Two-Terminal dc Line Link Data
Scheduled voltage must exceed mode switch voltage.

Invalid metered end code.
Integer NERR
PSS/E-29
2-21

Two-Terminal dc Line Converter Data
2.13 Two-Terminal dc Line Converter Data

TWO_TERMINAL_DC_CONVERTER_API(CNVFLG, NDC, INTGAR, REALAR, CKTAR,
IERR, NERR)
or
BAT_TWO_TERMINAL_DC_CONVERTER_DATA
CNVFLG
NDC
CKTAR
where:
Integer CNVFLG
Is the converter type.

CNVFLG = 1, for rectifier data (X7RECT).
CNVFLG = 2, for inverter data (X7INVR).
Integer NDC
Integer INTGAR(5)

INTGAR(1), converter bus number.
INTGAR(2), number of bridges in series.
INTGAR(3), zero or bus number of firing angle bus.
INTGAR(4), zero or bus number of winding one side of ac transformer.
INTGAR(5), zero or bus number of winding two side of ac transformer.
Integer REALAR(15)

REALAR(1), minimum firing angle.
REALAR(2), maximum firing angle.
REALAR(3), commutating resistance.
REALAR(4), commutating reactance.
REALAR(5), primary base voltage (ac).
REALAR(6), transformer ratio.
REALAR(7), tap setting.
REALAR(8), maximum tap setting.
REALAR(9), minimum tap setting.
REALAR(10), tap step.
REALAR(11), capacitive reactance of CCC type converter.
REALAR(12), firing angle (output only).
REALAR(13), dc voltage (kV) (output only).
REALAR(14), real power into converter (PWRCOD) (output only).
REALAR(15), reactive power into converter (PWRCOD) (output only).
Character CKTAR*2
Is an ac transformer circuit identifier.
2-22
PSS/E-29

Two-Terminal dc Line Converter Data
Integer IERR

IERR = 4, CNVFLG is not 1 or 2.
IERR = 5, transformer circuit identifier is more than two characters.
IERR = 6, no converter bus specified or bus not found.
Converter bus is dummy bus of a multi-section line.
Converter maximum angle less than minimum angle.
Converter maximum tap less than minimum tap.
Invalid tap step.
Commutating bus not found.
ac transformer bus not found.
Specified branch not found.
Specified branch is not a transformer.
From bus of specified branch is not winding one side bus.
Integer NERR
PSS/E-29
2-23

VSC dc Line Data
2.14 VSC dc Line Data

VSC_DC_LINE_API(NAMEAR, INTGAR, REALAR, IERR, NERR)
or
BAT_VSC_DC_LINE_DATA
NAMEAR
where:
Character NAMEAR*8 Is the VSC dc line name.
Integer INTGAR(5)
Is an array of at least five elements. The values are as follows:

INTGAR(1), control mode (0 or 1).
INTGAR(2), first owner number
Integer REALAR(5)
Is an array of at least five elements. The values are as follows:

REALAR(1), dc line resistance.
Integer IERR

IERR = 2, VSC dc line table full.
Invalid line resistance.
Integer NERR
2-24
PSS/E-29

VSC dc Line Converter Data
2.15 VSC dc Line Converter Data

VSC_DC_LINE_CONVERTER_API(NAMEAR, IC, INTGAR, REALAR, IERR, NERR)
or
BAT_VSC_DC_LINE_CONVERTER_DATA
NAMEAR
IC,
where:
Integer IC
Is the dc converter index (1 or 2).
Integer INTGAR(4)
Is the array of at least four elements. The values are as follows:

INTGAR(1), converter bus external number.
INTGAR(2), dc control code (0 = out-of-service, 1 = kV, 2 = MW).
INTGAR(3), ac control code (1 = voltage, 2 = pf).
INTGAR(4), remote bus external number.
Integer REALAR(11)
Is an array of at least eleven elements. The values are as follows:

REALAR(1), dc setpoint (kV or MW).
REALAR(2), ac setpoint (pu voltage or pf).
REALAR(3), "A" loss coefficient (kW).
REALAR(4), "B" loss coefficient (kW/amps).
REALAR(5), minimum converter losses (kW).
REALAR(6), converter ac MVA rating.
REALAR(7), converter ac current rating (amps).
REALAR(8), power weighting factor fraction.
REALAR(9), reactive power upper limit (Mvar).
REALAR(10), reactive power lower limit (Mvar).
REALAR(11), percent of contributed vars.
Integer IERR

IERR = 1, IC is not 1 or 2.
IERR = 3, VSC dc line not in case.
PSS/E-29
2-25

VSC dc Line Converter Data

Invalid dc control code.
Invalid ac control code.
Remote bus type code is not 1 or 2.
Converter specified is remotely regulating itself.
dc voltage setpoint is not positive.
ac voltage setpoint is not positive.
Invalid power weighting factor fraction.
MAXQ is less than MINQ.
RMPCT is not positive.
Integer NERR
2-26
PSS/E-29

Multi-Terminal dc Line
2.16 Multi-Terminal dc Line

MULTI_TERMINAL_DC_LINE_API(NDC,I NTGAR, REALAR, IERR, NERR)
or
BAT_MULTI_TERMINAL_DC_LINE_DATA
NDC
INTGAR(1)
REALAR(1)
where:
Integer NDC
Integer INTGAR(8)
Is an array of eight elements. The values are as follows:

Section 4.1.1.12, MDC).
INTGAR(2), positive pole voltage controlling converter index (output
only).
INTGAR(3), negative pole voltage controlling converter index or zero if
the negative pole is not being modelled (output only).
INTGAR(4), positive pole voltage continue converter bus extension
number (output only).
INTGAR(5), positive pole voltage continue converter bus extension
number (output only).
INTGAR(6), number of converters (1 to MXCONV) (output only).
INTGAR(7), number of dc buses (1 to MXDCBS) (output only).
INTGAR(8), number of dc links (1 to MXDCKT) (output only).
Integer REALAR(1)

REALAR(1), mode switch dc voltage (kV).
Integer IERR

Integer NERR
PSS/E-29
2-27

Multi-Terminal dc Line Converter Data
2.17 Multi-Terminal dc Line Converter Data

MULTI_TERMINAL_DC_CONVERTER_API(NDC, INTGAR, REALAR, IERR, NERR)
or
BAT_MULTI_TERMINAL_DC_CONVERTER_DATA
NDC
where:
Integer NDC
Integer INTGAR(4)
Is the array of four elements. The values are as follows:

INTGAR(1), converter bus number.
INTGAR(2), number of bridges in series.
INTGAR(3), pole code (> or = 0 => positive, < 0 => negative).
INTGAR(4), poles voltage controlling converter flag (< or = 0 => no, >0
=> yes).
Integer REALAR(17)
Is an array of seventeen elements. The values are as follows:

REALAR(1), scheduled current (amps), power (MW) or voltage (kv).
REALAR(2), minimum firing angle.
REALAR(3), maximum firing angle.
REALAR(4), transformer ratio.
REALAR(5), commutating resistance.
REALAR(6), commutating reactance.
REALAR(7), primary base voltage (ac).
REALAR(8), tap setting.
REALAR(9), maximum tap setting.
REALAR(10), minimum tap setting.
REALAR(11), tap step.
REALAR(12), margin (pu).
REALAR(13), converter participation factor.
REALAR(14), firing angle (output only).
REALAR(15), converter current (amps) (output only).
REALAR(16), real power into converter (PWRCOD) (output only).
REALAR(17), reactive power into converter (PWRCOD) (output only).
2-28
PSS/E-29

Multi-Terminal dc Line Converter Data
Integer IERR

IERR = 4, too many converters.
Invalid number of bridges.
Invalid base ac voltage.
Converter maximum angle less than minimum angle.
Converter maximum tap less than minimum tap.
Invalid tap step.
Another converter is assigned as its pole's voltage controlling converter.
Its voltage setpoint is not positive.
Its voltage setpoint is less than mode switch voltage.
Converter must remain its pole's voltage controlling.
Converter since it is the only converter on the pole.
Integer NERR
PSS/E-29
2-29

Multi-Terminal dc Line dc Bus Data
2.18 Multi-Terminal dc Line dc Bus Data

MULTI_TERMINAL_DC_BUS_API(NDC, IC, INTGAR, REALAR, NAMEAR, IERR,
NERR)
or
BAT_MULTI_TERMINAL_DC_BUS_DATA
REALAR(1)
NAMEAR
NDC
where:
Integer NDC
Integer IC
Is the dc bus number (must be positive).
Integer INTGAR(5)

INTGAR(1), converter bus number or zero.
INTGAR(5), second dc bus number.
Integer REALAR(2)

REALAR(1), resistance to ground.
REALAR(2), dc voltage (kV) (output only).
Character NAMEAR*8 Is the bus name.

Integer IERR

IERR = 3, dc line not in case.
IERR = 4, invalid dc bus number.
Data for lower numbered dc bus not yet entered.
Converter bus not found.
Bus is not a converter in this multi-terminal dc line.
Invalid second dc bus number.
dc bus no longer connected to converter as first dc bus.
dc bus no longer connected to converter as second dc bus.
2-30
PSS/E-29

Multi-Terminal dc Line dc Bus Data
Bus invalid as second dc bus since it is the first dc bus of another

converter.
Invalid area/zone/owner number.
Integer NERR
PSS/E-29
2-31

Multi-Terminal dc Line dc Link Data
2.19 Multi-Terminal dc Line dc Link Data

MULTI_TERMINAL_DC_LINK_API(NDC, IBUS, JBUS, CKT, INTGAR, REALAR,
IERR, NERR)
or
BAT_MULTI_TERMINAL_DC_LINK_DATA
NDC
INTGAR(1)
REALAR (1)
REALAR(2)
IBUS
JBUS
CKT
where:
Integer NDC
Integer IBUS
Is the dc bus number of "from" bus (must be positive).
Integer JBUS
Is the dc bus number of "to" bus (must be positive).
Character CKT*1
Integer INTGAR(1)

INTGAR(1), metered end dc bus number.
Integer REALAR(2)

REALAR(1), dc link resistance.
REALAR(2), dc link inductance.
Integer IERR

IERR = 3, dc line not in case.
IERR = 4, invalid dc bus number.
IERR = 5, circuit identifier is more than one character.
IERR = 7, too many dc links.
IERR = 8, dc bus not found in this multi-terminal dc line.
Invalid RDC.
Invalid XDC.
Integer NERR
2-32
PSS/E-29

Switched Shunt Data
2.20 Switched Shunt Data

SWITCHED_SHUNT_API(IARG, INTGAR, REALAR, NAMEAR, IERR, NERR)
or
BAT_SWITCHED_SHUNT_DATA
IARG
NAME
INTGAR (1)...INTGAR(10)
where:
Integer IARG
Is the bus number.
Integer INTGAR(10)
Is an array of at least ten elements. The values are as follows:

INTGAR(1), number of steps for block 1.
INTGAR(2), number of steps for block 2
Section 4.1.1.10, MODSW).
INTGAR(10), remote bus external number.
Integer REALAR(11)
Is an array of at least eleven elements. The values are as follows:

REALAR(1), admittance increment per step for block 1.
REALAR(9), desired voltage upper limit.
REALAR(10), desired voltage lower limit.
REALAR(11), present switched shunt admittance.
PSS/E-29
2-33

Switched Shunt Data
Integer IERR

IERR = 2, switched shunt table full.
VSC dc line not found.
Voltage controlling switched shunt specified as remotely regulating
itself.
Remote bus type code is not one.
VHIGH is less than VLOW.
No remote bus specified for plant or VSC converter control.
Remote bus has no generation for plant control.
No valid VSC dc line specified for VSC converter control.
Remote bus is not a converter of the specified VSC dc line.
For VSC converter control.
VLOW is not less than VHIGH for plant or VSC converter control.
VHIGH is not less than 1.0 for plant or VSC converter control.
VLOW is not greater than 0.0 for plant or VSC converter control.
Block has n or b zero and the other non-zero.
Invalid number of steps in block.
Block with non-zero n is beyond a previous n=0 block.
Block 1 has no steps.
Reactor block is out of sequence.
Initial admittance is below minimum.
Initial admittance is above maximum.
Initial admittance is not on a step.
Block has admittances with different signs in.
Positive and zero-sequences.
Integer NERR
2-34
PSS/E-29

Multi-Section Line Data
2.21 Multi-Section Line Data

MULTI_SECTION_LINE_API(IARG, JARG, CKT, INTGAR, IERR, NERR)
or
BAT_MULTI_SECTION_LINE_DATA
IARG
JARG
CKT
where:
Integer IARG
Integer JARG
Character CKT*2
Is a multi-section line identifier; CKT(1:1) must be &.
Integer INTGAR(10)
Is an array of ten elements. The values are as follows:

INTGAR(1), metered end bus number.
INTGAR(2-10), entries 2 through 10 are the bus numbers of the "dummy"
buses encountered along this multi-section line, starting with the bus to
which bus IBUS is connected and ending with the bus to which bus
JBUS is connected; entries used are 2 through n, where n is the number of
"dummy" buses; entries n+1 through MSLDM9 must be set to 0.
Integer IERR

IERR = 2, multi-section line identifier is more than two characters.
IERR = 3, multi-section line identifier does not start with &.
IERR = 4, no dummy buses specified.
IERR = 5, line section not found.
IERR = 6, circuit already in another multi-section line.
IERR = 7, bus appears more than once in multi-section line path.
IERR = 8, dummy bus does not have exactly two branches connected to it.
IERR = 9, dummy bus is a converter bus of a dc line.
IERR = 10, facts device is connected to a dummy bus.
IERR = 11, line section table is full.
IERR = 12, multi-section line table is full.
Integer NERR
PSS/E-29

2-35

Multi-Section Line Edit
2.22 Multi-Section Line Edit

MULTI_SECTION_LINE_EDIT_API(IARG, JARG, CKT, INTGAR, IERR, NERR)
or
BAT_MULTI_SECTION_LINE_EDIT
INTGAR(2)
IARG
JARG
CKT
INTGAR(1)
where:
Integer IARG
Integer JARG
Character CKT*2
Is the multi-section line identifier; CKT(1:1) must be&.
Integer INTGAR(2)

INTGAR(1), branch status.
INTGAR(1) = 1, in-service.
INTGAR(1) = 0, out-of-service.
INTGAR(2), metered end bus external number.
Integer IERR

IERR = 2, multi-section line identifier is more than two characters.
IERR = 3, multi-section line identifier does not start with "&".
IERR = 4, multi-section line not found.
Integer NERR
2-36
PSS/E-29

Transformer Impedance Correction Table Data
2.23 Transformer Impedance Correction Table Data

IMPEDANCE_CORRECTION_TABLE_API(I, INTGAR, REALAR, IERR, NERR)
or
BAT_IMPEDANCE_CORRECTION_TABLE_DATA
I
REALAR(1,1)
REALAR(2,1)
REALAR(1,2)
REALAR(2,2)...REALAR(1,11)
REALAR(2,11)
where:
Integer I
Is the table number (must be positive).
Integer INTGAR(2)

INTGAR(1), number of entries in table (API output).
INTGAR(2), table type flag (0=ratio, 1=angle) (API output).
Integer REALAR(2,11) Is an array dimensioned (2,11). The values are as follows:

REALAR(1-22), unused points must be specified as 0.,0.
Integer IERR

IERR = 1, invalid table number.
IERR = 3, ABSCISSA values not in ascending order.
IERR = 4, ABSCISSA value out of range of -180 to +180.
IERR = 5, table has fewer than 2 points.
Point is beyond previous end of table.
Invalid scaling factor.
Integer NERR
PSS/E-29
2-37

Inter-Area Transfer Data
2.24 Inter-Area Transfer Data

TRANSFER_API(APPLYF, IA, JA, ID, REALAR, IERR, NERR)
or
BAT_TRANSFER_DATA
APPLYF
IA
JA
ID
REALAR(1)
where:
Integer APPLYF
APPLYF = 1, to modify "from" and "to" area DESINT entries (X7APLY).

APPLYF = 2, to leave DESINT entries unchanged (X7NOAP).
Integer IA
Is the "from" area number.
Integer JA
Is the "to" area number.
Character ID*1
Is the inter-area transfer identifier.
Integer REALAR(1)

REALAR(1), MW comprising this inter-area transfer.
Integer IERR

IERR = 1, invalid area number.
IERR = 2, inter-area transfer identifier is more than one character.
IERR = 4, invalid apply option.
IERR = 5, invalid inter-area transfer identifier.
IERR = 6, transfer from an area to itself.
IERR = 7, inter-area transfer table full.
Changes to DESINT if "APPLYF" = 1.
Integer NERR
2-38
PSS/E-29

Solution Parameters
2.25 Solution Parameters

SOLUTION_PARAMETER_API(INTGAR, REALAR, IERR, NERR)
or
BAT_SOLUTION_PARAMETERS
where:
Integer INTGAR(3)
Is an array of three elements. The values are as follows:

INTGAR(1), Gauss-Seidel maximum number of iterations.
INTGAR(2), Newton-Raphson maximum number of iterations.
INTGAR(3), TYSL maximum number of iterations.
Integer REALAR(14)
Is an array of fourteen elements. The values are as follows:

REALAR(1), Gauss-Seidel real component acceleration factor.
REALAR(2), Gauss-Seidel IMAG component acceleration factor.
REALAR(3), special MSLV acceleration factor.
REALAR(4), Gauss-Seidel convergence tolerance.
REALAR(5), Newton-Raphson acceleration factor.
REALAR(6), Newton-Raphson convergence tolerance.
REALAR(7), TYSL acceleration factor.
REALAR(8), TYSL convergence tolerance.
REALAR(9), blow-up threshold.
REALAR(10), constant power load characteristic breakpoint.
REALAR(11), zero impedance line threshold.
REALAR(12), automatic adjustment threshold tolerance.
REALAR(13), tap movement deceleration factor.
REALAR(14), maximum tap change per adjustment.
Integer IERR

None.
Integer NERR
PSS/E-29
2-39

Change External Bus Number
2.26 Change External Bus Number

BUS_NUMBER_API(IARG, NEWBUS, IERR, NERR)
or
BAT_BUS_NUMBER
IARG
NEWBUS;
where:
Integer IARG
Is the current bus number to be changed.
Integer NEWBUS
Is the new bus number.
Integer IERR

IERR = 1, bus IARG not found.
IERR = 2, invalid new bus number.
IERR = 3, bus newbus already assigned to another bus.
None.
Integer NERR
2-40
PSS/E-29

Two-Line Case Title Data
2.27 Two-Line Case Title Data

CASE_TITLE_API(LINE1, LINE2, IERR, NERR)
or
BAT_CASE_TITLE_DATA
LINE1
LINE2
where:
Character LINE1*60
Is the first title line.
Character LINE2*60
Is the second title line.
Integer IERR

None.
Integer NERR
PSS/E-29
2-41

Long Case Title Data
2.28 Long Case Title Data

LONG_TITLE_API(LNGLNS, IERR, NERR)
or
BAT_LONG_TITLE_DATA
LNGLNS(1)...LNGLNS(16)
where:
Character LNGLNS*72 Is an array of sixteen title line.
Integer IERR

None.
Integer NERR
2-42
PSS/E-29

Bus Sequence Data
2.29 Bus Sequence Data

SEQ_BUS_API(IARG, REALAR, IERR, NERR)
or
BAT_SEQ_BUS_DATA
IARG
where:
Integer IARG
Is the bus number.
Integer REALAR(4)

REALAR(1), negative sequence shunt admittance real part.
REALAR(2), negative sequence shunt admittance reactive part.
REALAR(3), zero-sequence shunt admittance real part.
REALAR(4), zero-sequence shunt admittance reactive part.
Integer IERR

None.
Integer NERR
PSS/E-29
2-43

Branch Sequence Data
2.30 Branch Sequence Data

SEQ_BRANCH_API(IARG, JARG, CKT, REALAR, IERR, NERR)
or
BAT_SEQ_BRANCH_DATA
IARG
JARG
CKT
where:
Integer IARG
Integer JARG
Character CKT*2
Integer REALAR(7)
Is an array of at least seven elements. The values are as follows:

REALAR(1), zero-sequence branch resistance.
REALAR(2), zero-sequence branch reactance.
REALAR(3), zero-sequence total line charging.
REALAR(4), zero-sequence real line shunt at bus IARG end.
REALAR(5), zero-sequence reactive line shunt at bus IARG end.
REALAR(6), zero-sequence real line shunt at bus JARG end.
REALAR(7), zero-sequence reactive line shunt at bus JARG end.
Integer IERR

IERR = 4, circuit identifier starts with "&".
Branch is Z.I.L., but zero-sequence impedance is non-zero.
Integer NERR
2-44
PSS/E-29

Two-Winding Transformer Sequence Data
2.31 Two-Winding Transformer Sequence Data

SEQ_TWO_WINDING_API(IARG, JARG, CKT, INTGAR, REALAR, IERR, NERR)
or
BAT_SEQ_TWO_WINDING_DATA
IARG
JARG
CKT
INTGAR(1)
where:
Integer IARG
Integer JARG
Character CKT*2
Integer INTGAR(1)

INTGAR(1), connection code (see Program Operation Manual,
Section 4.91.1.9, CC).
Integer REALAR(4)

REALAR(1), grounding resistance.
REALAR(2), grounding reactance.
REALAR(3), zero-sequence transformer resistance.
REALAR(4), zero-sequence transformer reactance.
Integer IERR

IERR = 6, branch is not a transformer.
Invalid winding connection code.
Branch is not a Z.I.L. but zero-sequence impedance is zero.
Integer NERR
PSS/E-29
2-45

Three-Winding Transformer Sequence Data
2.32 Three-Winding Transformer Sequence Data

SEQ_THREE_WINDING_API(IARG, JARG, KARG, CKT, INTGAR, REALAR, IERR,
NERR)
or
BAT_SEQ_THREE_WINDING_DATA
IARG
INTGAR(1)
JARG
KARG
CKT
where:
Integer IARG
Is the bus number of one of the buses.
Integer JARG
Integer KARG
Character CKT*2
Is the transformer circuit identifier.
Integer INTGAR(1)

INTGAR(1), connection code (see Program Operation Manual,
Section 4.91.1.9, CC).
Integer REALAR(8)
Is an array of at least eight elements. The values are as follows:

REALAR(1), winding one grounding resistance.
REALAR(2), winding one grounding reactance.
REALAR(3), zero-sequence winding one resistance.
REALAR(4), zero-sequence winding one reactance.
REALAR(5), zero-sequence winding two resistance.
REALAR(6), zero-sequence winding two reactance.
REALAR(7), zero-sequence winding three resistance.
REALAR(8), zero-sequence winding three reactance.
Integer IERR

IERR = 4, transformer not found.
2-46
PSS/E-29

Three-Winding Transformer Sequence Data

Invalid winding connection code.
Connection code is such that more than one-winding requires.
A grounding impedance.
Integer NERR
PSS/E-29
2-47

Machine Sequence Data
2.33 Machine Sequence Data

SEQ_MACHINE_API(IARG, MCID, REALAR, IERR, NERR)
or
BAT_SEQ_MACHINE_DATA
IARG
MCID
where:
Integer IARG
Is the bus number.
Character MDID*2
Integer REALAR(6)

REALAR(1), machine positive-sequence fault analysis resistance.
REALAR(2), machine positive-sequence fault analysis reactance.
REALAR(3), machine negative-sequence fault analysis resistance.
REALAR(4), machine negative-sequence fault analysis reactance.
REALAR(5), machine zero-sequence fault analysis resistance.
REALAR(6), machine zero-sequence fault analysis reactance.
Integer IERR

IERR = 3, machine identifier is more than two characters.
IERR = 4, machine not found.
None.
Integer NERR
2-48
PSS/E-29

Switched Shunt Zero-Sequence Data
2.34 Switched Shunt Zero-Sequence Data

SEQ_SWITCHED_SHUNT_API(IARG, REALAR, IERR, NERR)
or
BAT_SEQ_SWITCHED_SHUNT_DATA
IARG
where:
Integer IARG
Is the bus number.
Integer REALAR(9)
Is an array of nine elements. The values are as follows:

REALAR(1), zero-sequence increment per step for block 1.
REALAR(9), present zero-sequence switched shunt admittance (output
only).
Integer IERR

IERR = 3, no switched shunt at bus.
Block has N zero and B non-zero.
Block has admittances with different signs in.
Positive and zero-sequences.
Integer NERR
PSS/E-29
2-49

Zero-Sequence Mutual Coupling Data
2.35 Zero-Sequence Mutual Coupling Data

SEQ_MUTUAL_API(IARG, JARG, CKT1, KARG, LARG, CKT2, REALAR, IERR,
NERR)
or
BAT_SEQ_MUTUAL_DATA
IARG
JARG
CKT1
KARG
LARG
CKT2
where:
Integer IARG
Is the bus number of first branch from bus.
Integer JARG
Is the bus number of first branch to bus.
Character CKT1*2
Is the first branch circuit identifier.
Integer KARG
Is the bus number of second branch from bus.
Integer LARG
Is the bus number of second branch to bus.
Character CKT2*2
Is the second branch circuit identifier.
Integer REALAR(6)

REALAR(1), branch-to-branch mutual resistance.
REALAR(2), branch-to-branch mutual reactance.
REALAR(3), B factor at IARG end of first branch.
REALAR(4), B factor at JARG end of first branch.
REALAR(5), B factor at KARG end of second branch.
REALAR(6), B factor at LARG end of second branch.
Integer IERR

IERR = 6, mutual couples a branch to itself.
IERR = 8, branch is a zero impedance line.
IERR = 9, mutual table is full.
2-50
PSS/E-29

Zero-Sequence Mutual Coupling Data

Invalid B factor (<0.0 or >1.0).
B1 is not less than B2.
Integer NERR
PSS/E-29
2-51
2-52
PSS/E-29
CHAPTER
3
OPTIMAL POWER FLOW APIS
The sections within this chapter contain descriptions of application programming interface (API)
calls and batch commands associated with the functions of the optimal power flow. The batch commands described are generated within PSS/E Response files and may be entered at the PSS/E
command line prompt. Further information on these commands can be found in the PSS/E OPF
Manual.
3.1 Data Initialization

3.1.1 NEWOPF
The following API introduces default OPF data records for all bus-oriented load flow data within
the working case. This includes bus voltage constraint records, OPF bus loads, and generator dispatch records. The command must be called prior to introducing any new OPF data records for the
first time. It has no affect if OPF data already resides within the working case.
The API is invoked through the subroutine call:
NEWOPF
or is issued as the following batch command:

BAT_NEWOPF
There are no arguments or error return codes.
PSS/E-29
3-1

Active Power Dispatch Tables
3.2 Active Power Dispatch Tables

The following API is used to add or modify individual active power dispatch table records within
the PSS/E working file. The API is invoked through the subroutine call:
OPFDSP_TBL_API(TBL, INTGAR, REALAR, IERR, NERR)
or may be issued as the following batch command:

BAT_OPF_APDSP_TBL
INTGAR(2) INTGAR(3)
TBL REALAR(1) REALAR(2) REALAR(3) INTGAR(1)
where:
Integer TBL
Is the active power dispatch table number.
Integer INTGAR(3)
Is an array of three integer elements. The value of each is as follows.

INTGAR(1) is the cost curve type.
INTGAR(1) = 1, polynomial or exponential cost curve.
INTGAR(1) = 2, linear cost curve.
INTGAR(1) = 3, quadratic cost curve.
INTGAR(2) is the active power dispatch table status.
INTGAR(2) = 0, out of service.
INTGAR(2) = 1, in service.
INTGAR(3) is the cost table cross reference number.
Real REALAR(3)
Is an array of three real elements. The value of each is as follows.

REALAR(1) is the maximum active power generation, in MW.
REALAR(2) is the minimum active power generation, in MW.
REALAR(3) is the fuel cost scale coefficient.
Integer IERR

IERR = 1, exceeded maximum number of allowable active power dispatch
tables.
IERR = -1, non-fatal error occurred. Warning messages are as follows:
Invalid cost curve type specified.
Invalid dispatch table status specified.
Maximum active power generation less than minimum active power
generation.
Integer NERR
The number of lines stored in the message buffer.
3-2
PSS/E-29

Adjustable Branch Reactances
3.3 Adjustable Branch Reactances

3.3.1 Individual Adjustable Branch Reactances
The following API is used to add or modify individual adjustable branch reactance data records
within the PSS/E working file. The API is invoked through the subroutine call:
ADJBRN_REAC_API(EIBUS, EJBUS, CKTID, INTGAR, REALAR, IERR, NERR)

BAT_OPF_ADJBRX_INDV
EIBUS EJBUS CKTID REALAR(1) REALAR(2)
REALAR(3) REALAR(4) INTGAR(1) INTGAR(2) INTGAR(3)
where:
Integer EIBUS
Is the "from bus" number.
Integer EJBUS
Is the "to bus" number.
Character*2 CKTID
Integer INTGAR(3)

INTGAR(1) is the cost table type.
INTGAR(2) is the adjustable branch reactance status.
Real REALAR(4)
Is an array of four real elements. The value of each is as follows.

REALAR(1) is the reactance multiplier in per unit.
REALAR(2) is the maximum reactance multiplier in per unit.
REALAR(3) is the minimum reactance multiplier in per unit.
REALAR(4) is the cost scale coefficient in $/per unit.
Integer IERR

IERR = 1, invalid bus number specified.
IERR = 2, exceeded maximum number of allowable branch reactance
entries.
IERR = 3, specified branch does not exist.
IERR = 4, specified branch cannot be a transformer.
PSS/E-29
3-3


Invalid branch reactance status specified.
Maximum branch reactance multiplier less than minimum multiplier.
Branch reactance multiplier cannot be less than 0.1.
Branch reactance multiplier cannot be set to zero.
Integer NERR
3.3.2 Adjustable Branch Reactance Data by Subsystem

The following API is used to add or modify OPF branch reactance data records within the PSS/E
working file, based upon a selected subsystem. The API is invoked through the subroutine call:
AXOBRXNW(SID, ALL, INTGAR, REALAR, RVAL, IERR, NERR)

BAT_OPF_ADJBRX_SUBSYS
SID
ALL
REALAR(1)
REALAR(2)
REALAR(3) REALAR(4) INTGAR(1) INTGAR(2) INTGAR(3) RVAL(1)
RVAL(2)
RVAL(3)
RVAL(4)
where:
Integer SID
Is a valid subsystem ID. Valid subsystem IDs range from 0 to 3. A subsystem must have been previously defined.
Integer ALL
Is the "all" buses or selected subsystem flag.

Integer INTGAR(3)

INTGAR(1) is the cost table type.
INTGAR(2) is the adjustable branch reactance status.
Real REALAR(4)
3-4

REALAR(1) is the reactance multiplier in per unit.
REALAR(2) is the maximum reactance multiplier in per unit.
REALAR(3) is the minimum reactance multiplier in per unit.
REALAR(4) is the cost scale coefficient in $/per unit.
PSS/E-29
Integer RVAL(4)

Is an array of four integer elements. The value of each element is defined

as follows:
RVAL(1) indicates how the value of REALAR(1) should be used:
RVAL(1) = 0, if the value of REALAR(1) is to be used as defined.
RVAL(1) = 1, if the value of REALAR(1) is to be multiplied by the present
value of the branch reactance multiplier.
RVAL(1) = 2, if the value of REALAR(1) is to be added to the present
value of the branch reactance multiplier.
value of the maximum branch reactance multiplier.
value of the maximum branch reactance multiplier.
value of the minimum branch reactance multiplier.
value of the minimum branch reactance multiplier.
value of the cost scale coefficient.
Integer IERR

IERR = 1, ALL or SID is invalid.
IERR = 2, exceeded maximum number of allowable branch reactance
entries.
Invalid branch reactance status specified.
Maximum branch reactance multiplier less than minimum multiplier.
Branch reactance multiplier cannot be less than 0.1.
Branch reactance multiplier cannot be set to zero.
Integer NERR
PSS/E-29
3-5

Adjustable Bus Loads
3.4 Adjustable Bus Loads

3.4.1 Individual Bus Loads
The following API is used to add or modify individual OPF bus load data records within the PSS/E
working file. The API is invoked through the subroutine call:
OPFBLD_INDV_API(EIBUS, LOADID, INTGAR, IERR, NERR)

BAT_OPF_LOAD_INDV
EIBUS LOADID INTGAR
where:
Integer EIBUS
Is the bus number.
Character*2 LOADID Is the bus load identifier.

Integer INTGAR
Is the adjustable bus load table cross reference number.
Integer IERR

IERR = 2, specified load does not exist.
Integer NERR
3.4.2 Bus Loads by Subsystem

The following API is used to add or modify OPF bus load data records within the PSS/E working
file, based upon a selected subsystem. This API is invoked through the subroutine call:
AXOBLDNW(SID, ALL, INTGAR, IERR, NERR)

BAT_OPF_LOAD_SUBSYS
SID
ALL
INTGAR(1)
INTGAR(2)
where:
Integer SID
Integer ALL

ALL = 1, process all buses, use existing data values.
ALL = 2, process all buses, use default data values.
3-6
PSS/E-29

Adjustable Bus Loads
Integer INTGAR(2)
Is an array of two integer elements. The value of each is as follows.

INTGAR(1) is the bus load table cross reference number.
INTGAR(2) indicates which bus types should be processed.
INTGAR(2) = 0, all buses in subsystem.
INTGAR(2) = 1, only type 1 buses in subsystem.
INTGAR(2) = 2, only type 2 and 3 buses in subsystem.
Integer IERR

IERR = 1, ALL or SID value is invalid.
Integer NERR
PSS/E-29
3-7

Adjustable Bus Load Tables
3.5 Adjustable Bus Load Tables

The following API is used to add or modify adjustable bus load table records within the PSS/E
OPFLOD_TBL_API(TBL, INTGAR, REALAR, IERR, NERR)

BAT_OPF_ADJLOAD_TBL
TBL REALAR(1) REALAR(2) REALAR(3) REALAR(4)
REALAR(5) REALAR(6) REALAR(7) INTGAR(1) INTGAR(2) INTGAR(3)
where:
Integer TBL
Is the adjustable bus load table number.
Integer INTGAR(3)

INTGAR(1) is the cost curve type.
INTGAR(2) is the adjustable bus load status.
Real REALAR(7)
Is an array of seven real elements. The value of each is as follows.

REALAR(1) is the load multiplier.
REALAR(2) is the maximum load multiplier.
REALAR(3) is the minimum load multiplier.
REALAR(4) is the load ratio multiplier.
REALAR(5) is the maximum load ratio multiplier.
REALAR(6) is the minimum load ratio multiplier.
REALAR(7) is the load cost scale coefficient.
Integer IERR

IERR = 1, exceeded maximum number of allowable load adjustment tables.
Invalid load table status.
Maximum load multiplier less than minimum load multiplier.
Maximum load ratio multiplier less than minimum load ratio multiplier.
Integer NERR
3-8
PSS/E-29

Adjustable Bus Shunts
3.6 Adjustable Bus Shunts

3.6.1 Individual Adjustable Bus Shunts
The following API is used to add or modify individual OPF adjustable bus shunt data records within
OPFVAR_INDV_API(EIBUS, SHNTID, INTGAR, REALAR, IERR, NERR)

BAT_OPF_ADJVAR_INDV
EIBUS SHNTID REALAR(1) REALAR(2) REALAR(3)
REALAR(4) INTGAR(1) INTGAR(2) INTGAR(3)
where:
Integer EIBUS
Is the bus number.
Character*1 SHNTID
Is the bus shunt identifier.
Integer INTGAR(3)

INTGAR(1) is the cost curve type:
INTGAR(1) = 1, polynomial and exponential curve.
INTGAR(1) = 2, piece-wise linear curve.
INTGAR(1) = 3, piece-wise quadratic curve.
INTGAR(2) is the status.
Real REALAR(4)

REALAR(1) is the initial bus shunt susceptance in Mvar at nominal
voltage.
REALAR(2) is the maximum bus shunt susceptance in Mvar.
REALAR(3) is the minimum bus shunt susceptance in Mvar.
REALAR(4) is the cost scale coefficient in $/Mvar.
Integer IERR

IERR = 2, invalid shunt identifier specified.
IERR = 3, exceeded maximum number of allowable adjustable bus shunt
entries.
PSS/E-29
3-9

IERR = -1, non-fatal error occurred. Possible warning messages are as

follows:
Invalid adjustable bus shunt status specified.
Maximum shunt susceptance less than minimum shunt susceptance.
Integer NERR
3.6.2 Adjustable Bus Shunts by Subsystem

The following API is used to add or modify OPF adjustable bus shunt records within the PSS/E
working file, based upon a selected subsystem. This API is invoked through the subroutine call:
AXOPVRNW(SID, ALL, AUTOADD, SHNTID, INTGAR, REALAR, RVAL, IERR,
NERR)

BAT_OPF_ADJVAR_SUBSYS
REALAR(1)
REALAR(2)
INTGAR(2)
INTGAR(3)
SID
ALL
AUTOADD SHNTID INTGAR(4)
REALAR(3)
REALAR(4)
INTGAR(1)
RVAL(1)
RVAL(2)
RVAL(3)
RVAL(4)
where:
Integer SID
Integer ALL

Integer AUTOADD
Indicates whether new records can be added.

AUTOADD = 0, do not add a new var record if it does not already exist.
AUTOADD = 1, add a new var record if it does not already exist.
AUTOADD = 2, add a separate shunt record at the bus.
AUTOADD = 3, only modify existing bus shunt records which correspond
to the shunt identifier given in SHNTID.
Character*1 SHNTID
Is an adjustable bus shunt identifier.
Integer INTGAR(4)
Is an array of four integer elements. The value of each is as follows.

INTGAR(1) is the cost curve type:
INTGAR(1) = 1, polynomial and exponential curve.
INTGAR(1) = 2, piece-wise linear curve.
INTGAR(1) = 3, piece-wise quadratic curve.
3-10
PSS/E-29

INTGAR(2) is the status.

Real REALAR(4)

REALAR(1) is the bus shunt susceptance in Mvar at nominal voltage.
REALAR(2) is the maximum bus shunt susceptance in Mvar.
REALAR(3) is the minimum bus shunt susceptance in Mvar.
REALAR(4) is the cost scale coefficient in $/Mvar.
Integer RVAL(4)
Is an array of four integer elements. The value of each element is defined

as follows:
value of the bus shunt susceptance.
value of the bus shunt susceptance.
value of the maximum bus shunt susceptance.
value of the maximum bus shunt susceptance.
value of the minimum bus shunt susceptance.
value of the minimum bus shunt susceptance.
PSS/E-29
3-11

Integer IERR

IERR = 1, ALL or SID is invalid.
IERR = 2, invalid shunt identifier specified.
IERR = 3, exceeded maximum number of allowable adjustable bus shunt
entries.
IERR = -1, non-fatal error occurred. Possible warning messages are as
follows:
Invalid adjustable bus shunt status specified.
Maximum shunt susceptance less than minimum shunt susceptance.
Integer NERR
3-12
PSS/E-29

Branch Flow Constraints
3.7 Branch Flow Constraints

3.7.1 Individual Branch Flow Constraints
The following API is used to add or modify individual branch or two-winding transformer flow
constraint records within the PSS/E working file.The API is invoked through the subroutine call:
OPFBRN_FLOW_API(EIBUS, EJBUS, CKTID, BFLWID, INTGAR, REALAR, IERR,
NERR)

BAT_OPF_BRFLW_BRN_INDV
EIBUS EJBUS CKTID BFLWID REALAR(1)
REALAR(2) REALAR(3) REALAR(4) INTGAR(1) INTGAR(2) REALAR(5)
The following API is used to add or modify flow constraint records for an individual winding of a
three-winding transformer within the PSS/E working file.The API is invoked through the subroutine call:
OPFBRN_FLOW_3WT_API(EIBUS, EJBUS, EKBUS, CKTID, BFLWID, INTGAR,
REALAR, IERR, NERR)

BAT_OPF_BRFLW_3WT_INDV
EIBUS EJBUS EKBUS CKTID BFLWID REALAR(1)
REALAR(2) REALAR(3) REALAR(4) INTGAR(1) INTGAR(2) REALAR(5)
where:
Integer EIBUS

For a three-winding transformer, the value of EIBUS indicates the "from
bus" of the winding for which the flow constraint is being introduced.
Integer EJBUS
Integer EKBUS
Is the "third bus" number, for specification of a three-winding transformer.
Character*2 CKTID
Character*1 BFLWID Is the branch flow constraint identifier.

Integer INTGAR(2)
Is an array of two integer elements. The value of each is as follows.

INTGAR(1) is the branch flow type.
INTGAR(1) = 1, MW.
INTGAR(1) = 2, Mvar.
INTGAR(1) = 3, MVA.
INTGAR(1) = 4, Ampere.
PSS/E-29
3-13

INTGAR(2) is the branch flow limit type.

INTGAR(2) = 0, reporting only.
INTGAR(2) = 1, hard limit imposed.
INTGAR(2) = 2, linear soft limit imposed.
INTGAR(2) = 3, quadratic soft limit imposed.
Real REALAR(5)
Is an array of five real elements. The value of each is as follows.

REALAR(1) is the maximum normal flow limit in physical units.
REALAR(2) is the minimum normal flow limit in physical units.
REALAR(3) is the maximum emergency flow limit in physical units.
REALAR(4) is the minimum emergency flow limit in physical units.
REALAR(5) is the soft limit penalty weight.
Integer IERR

IERR = 2, exceeded maximum number of allowable branch flow constraint entries.
IERR = 3, specified branch/three-winding transformer does not exist.
IERR = -1, non-fatal error occurred. Possible warning messages are:
Invalid branch flow type specified.
Invalid branch flow limit type specified.
Maximum normal flow limit is less than the minimum normal flow
limit.
Maximum emergency flow limit is less than the minimum emergency
flow limit.
Integer NERR
3.7.2 Branch Flow Constraints by Subsystem

The following API is used to add or modify branch flow data records within the PSS/E working file,
based upon a selected subsystem. This API is invoked through the subroutine call:
AXOBFLNW(SID, ALL, AUTOADD, BFLWID, INTGAR, REALAR, RVAL, IERR,
NERR)

BAT_OPF_BRFLW_SUBSYS
REALAR(2)
REALAR(3)
INTGAR(3)
REALAR(5)
RVAL(5)
3-14
SID
ALL AUTOADD BFLWID REALAR(1)
REALAR(4)
INTGAR(1) INTGAR(2)
RVAL(1)
RVAL(2)
RVAL(3)
RVAL(4)
PSS/E-29

where:
Integer SID
Integer ALL

Integer AUTOADD
Indicates whether new records can be added.

AUTOADD = 0, do not add a new branch flow record if it does not already
exist.
AUTOADD = 1, add a new branch flow record if it does not already exist.
AUTOADD = 2, only modify existing branch flow records which correspond to the flow identifier given in BFLWID.
Character*1 BFLWID Is the branch flow identifier.

Integer INTGAR(3)

INTGAR(1) is the branch flow type.
INTGAR(1) = 1, MW.
INTGAR(1) = 3, MVA.
INTGAR(1) = 4, Ampere.
INTGAR(2) is the branch flow limit type.
INTGAR(2) = 1, hard limit imposed.
INTGAR(2) = 2, linear soft limit imposed.
INTGAR(2) = 3, quadratic soft limit imposed.
INTGAR(3) is the default rate setting.
INTGAR(3) = 0, use the limits that have been defined.
INTGAR(3) = 1, base flow limits on RATEA.
INTGAR(3) = 2, base flow limits on RATEB.
INTGAR(3) = 3, base flow limits on RATEC.
Real REALAR(5)
PSS/E-29
Is an array of five real elements. The value of each is as follows.

REALAR(1) is the maximum normal flow limit in physical units.
REALAR(2) is the minimum normal flow limit in physical units.
REALAR(3) is the maximum emergency flow limit in physical units.
REALAR(4) is the minimum emergency flow limit in physical units.
3-15

Integer RVAL(5)
Is an array of five integer elements. The value of each element is defined

as follows:
value of the maximum normal flow limit.
value of the maximum normal flow limit.
value of the minimum normal flow limit.
value of the minimum normal flow limit.
value of the maximum emergency flow limit.
value of the maximum emergency flow limit.
value of the minimum emergency flow limit.
value of the minimum emergency flow limit.
value of the soft limit penalty weight.
Integer IERR
3-16

IERR = 2, exceeded maximum number of allowable branch flow constraint entries.
PSS/E-29


Invalid flow type specified.
Invalid branch flow limit type specified.
Maximum normal flow limit is less than the minimum normal flow
limit.
Maximum emergency flow limit is less than the minimum emergency
flow limit.
Integer NERR
PSS/E-29
3-17

Bus Voltage Magnitude Constraints
3.8 Bus Voltage Magnitude Constraints

3.8.1 Individual Bus Voltage Records
The following API is used to modify individual OPF bus voltage magnitude data records within the
PSS/E working file. The API is invoked through the subroutine call:
OPFBUS_INDV_API(EIBUS, INTGAR, REALAR, IERR, NERR)

BAT_OPF_BUS_INDV
EIBUS REALAR(1) REALAR(2) REALAR(3) REALAR(4)
INTGAR(1) REALAR(5) INTGAR(2)
where:
Integer EIBUS
Is the bus number.
Integer INTGAR(2)
Is an array of two integer elements whose value is as follows.

INTGAR(1) is the limit type.
INTGAR(1) = 1, hard limit.
INTGAR(1) = 2, linear soft limit.
INTGAR(1) = 3, quadratic soft limit.
INTGAR(2) indicates what to do with the defined voltage limit.
INTGAR(2) = 0, leave voltage limits as defined by REALAR(1) and
REALAR(2).
INTGAR(2) = 1, fix normal voltage limit at present voltage values,
ignoring any values defined by REALAR(1) and REALAR(2).
INTGAR(2) = 2, allow normal voltage limits to open up if they exceed the
bounds defined by REALAR(1) and REALAR(2).
Real REALAR(5)
Is an array of five real elements whose value is as follows.

REALAR(1) is the normal maximum voltage limit in pu.
REALAR(2) is the normal minimum voltage limit in pu.
REALAR(3) is the emergency maximum voltage limit in pu.
REALAR(4) is the emergency minimum voltage limit in pu.
REALAR(5) is the soft-limit penalty weight.
Integer IERR

3-18
PSS/E-29


Invalid limit type specified.
Maximum normal voltage limit less than minimum limit.
Maximum emergency voltage limit less than minimum limit.
Integer NERR
3.8.2 Bus Voltage Constraints by Subsystem

This API is used to modify OPF bus attribute records within the PSS/E working file, based upon a
selected subsystem. This API is invoked through the subroutine call:
AXOPBSNW(SID, ALL, INTGAR, REALAR, RVAL, IERR, NERR)

BAT_OPF_BUS_SUBSYS
SID
ALL
INTGAR(3) INTGAR(2)
REALAR(1)
REALAR(2) REALAR(3)
REALAR(4)
INTGAR(1)
REALAR(5)
RVAL(1)
RVAL(2)
RVAL(3)
RVAL(4)
RVAL(5)
where:
Integer SID
Integer ALL

Integer INTGAR(3)
Is an array of three integer elements whose value is as follows.

INTGAR(1) is the limit type.
INTGAR(2) indicates what to do with the defined voltage limit.
INTGAR(2) = 0, leave voltage limits as defined by REALAR(1) and
REALAR(2).
INTGAR(2) = 1, fix normal voltage limit at present voltage values,
ignoring any values defined by REALAR(1) and REALAR(2).
INTGAR(2) = 2, allow normal voltage limits to open up if they exceed the
bounds defined by REALAR(1) and REALAR(2).
PSS/E-29
3-19

Real REALAR(5)

REALAR(1) is the normal maximum voltage limit in pu.
REALAR(2) is the normal minimum voltage limit in pu.
REALAR(3) is the emergency maximum voltage limit in pu.
REALAR(4) is the emergency minimum voltage limit in pu.
REALAR(5) is the soft-limit penalty weight.
Integer RVAL(5)

as follows:
value of the normal bus voltage minimum limit.
value of the normal bus voltage minimum limit.
value of the normal bus voltage maximum limit.
value of the normal bus voltage maximum limit.
value of the emergency bus voltage minimum limit.
value of the emergency bus voltage minimum limit.
value of the emergency bus voltage maximum limit.
value of the emergency bus voltage maximum limit.
3-20
PSS/E-29

Integer IERR

Invalid limit type specified.
Maximum normal voltage limit less than minimum limit.
Maximum emergency voltage limit less than minimum limit.
Integer NERR
PSS/E-29
3-21

Cost Curve Tables
3.9 Cost Curve Tables

3.9.1 Linear Cost Curve Table
The following API is used to add or modify a linear cost curve record within the PSS/E working
file. The API is invoked through the subroutine call:
CSTTBL_LIN_API(TBL, LABL, NPRS, X1, Y1, ..., XNPRS, YNPRS, IERR,
NERR)

BAT_OPF_CSTTBL_LIN
TBL LABL NPRS
X1, Y1
...
XNPRS, YNPRS
where:
Integer TBL
Is the linear cost curve table number.
Character*12 LABL
Is the cost table description of, at most, 12 characters.
Integer NPRS
Is the number of Xi, Yi coordinate pairs being specified.
Real Xi
Is the control variable value.
Real Yi
Is the incremental cost or energy consumption value.
Integer IERR

IERR = 1, exceeded maximum number of allowable cost tables.
IERR = 2, exceeded maximum number of allowable cost curve data pairs.
IERR = 3, coordinate values are not monotonic.
Integer NERR
3.9.2 Quadratic Cost Curve Tables

The following API is used to add or modify a quadratic cost curve record within the PSS/E working
file. The API is invoked through the subroutine call:
CSTTBL_QUAD_API(TBL, LABL, REALAR, NPRS, X1, Y1, ..., XNPRS,
YNPRS, IERR, NERR)
3-22
PSS/E-29

Cost Curve Tables

BAT_OPF_CSTTBL_QUAD
TBL LABL REALAR(1) NPRS
X1, Y1
...
XNPRS, YNPRS
where:
Integer TBL
Is the quadratic cost curve table number.
Character*12 LABL
Real REALAR(1)
Is an array of one integer element whose value is as follows.

REALAR(1) is the cost integration constant.
Integer NPRS
Is the number of Xi, Yi coordinate pairs to be specified.
Real Xi
Is the control variable value.
Real Yi
Is the incremental cost or energy consumption value.
Integer IERR

IERR = 2, exceeded maximum number of allowable cost curve data pairs.
IERR = 3, coordinate values are not monotonic.
Integer NERR
3.9.3 Polynomial Cost Curve Tables

This API is used to add or modify a polynomial and exponential cost curve record within the PSS/E
CSTTBL_POLY_API(TBL, LABL, REALAR, LINCST, QUACST, EXPCST, EXPON,
IERR, NERR)

BAT_OPF_CSTTBL_POLY
EXPON
PSS/E-29
TBL LABL REALAR(1) LINCST QUACST EXPCST
3-23

Cost Curve Tables
where:
Integer TBL
Is the polynomial and exponential cost curve table number.
Character*12 LABL
Real REALAR(1)

REALAR(1) is the cost integration constant.
Real LINCST
Is the linear cost coefficient value.
Real QUACST
Is the quadratic cost coefficient value.
Real EXPCST
Is the exponential cost coefficient value.
Real EXPON
Is the exponent of the exponential cost coefficient.
Integer IERR

IERR = 2, exceeded maximum number of allowable cost curve data
values.
Integer NERR
3-24
PSS/E-29

Generator Dispatch Data
3.10 Generator Dispatch Data

3.10.1 Individual Generator Dispatch Records
The following API is used to modify individual generator dispatch data records within the PSS/E
GENDSP_INDV_API(EIBUS, GENID, INTGAR, REALAR, IERR, NERR)

BAT_OPF_GENDSP_INDV
EIBUS GENID REALAR(1) INTGAR(1)
where:
Integer EIBUS
Is the bus number.
Character*2 GENID
Integer INTGAR(1)

INTGAR(1) is the active power dispatch table cross reference number.
Real REALAR(1)
Is an array of one real element whose value is as follows.

REALAR(1) is the dispatch fraction.
Integer IERR

IERR = 2, specified machine does not exist.
Integer NERR
3.10.2 Generator Dispatch Data By Subsystem

The following API is used to modify OPF generator dispatch data records within the PSS/E working
file, based upon a selected subsystem. This API is invoked through the use of the statement:
AXODSPNW(SID, ALL, INTGAR, REALAR, RVAL, IERR, NERR)
or may be issued by the following batch command:

BAT_OPF_GENDSP_SUBSYS
SID
ALL
REALAR(1)
INTGAR(1)
RVAL(1)
where:
Integer SID
PSS/E-29
3-25

Generator Dispatch Data
Integer ALL

Integer INTGAR(1)

INTGAR(1) is the active power dispatch table cross reference number.
Real REALAR(1)

REALAR(1) is the dispatch fraction.
Integer RVAL(1)
Is an array of one integer element. The value of the element is defined as

follows:
value of the dispatch fraction.
value of the dispatch fraction.
Integer IERR

Integer NERR
3-26
PSS/E-29

Generation Reactive Capability Data
3.11 Generation Reactive Capability Data

3.11.1 Individual Generation Reactive Capability Records
The following API is used to add or modify individual generation reactive capability data records
within the PSS/E working file. The API is invoked through the subroutine call:
GEN_RCAP_API(EIBUS, GENID, INTGAR, REALAR, IERR, NERR)

BAT_OPF_GEN_RCAP_INDV
EIBUS GENID REALAR(1) REALAR(2) REALAR(3)
REALAR(4) REALAR(5) INTGAR(1)
where:
Integer EIBUS
Is the bus number.
Character*2 GENID
Integer INTGAR(1)

INTGAR(1) is the reactive capability limit status:
INTGAR(1) = 1, in service, no reactive generation limits.
INTGAR(1) = 2, in service, inhibiting field increase.
INTGAR(1) = 3, in service, inhibiting field decrease.
INTGAR(1) = 4, in service, fixed Efd.
INTGAR(1) = 5, in service, apply reactive generation limits.
Real REALAR(5)

REALAR(1) is the direct-axis synchronous reactance in pu on Mbase.
REALAR(2) is the stator current limit in pu on Mbase.
REALAR(3) is the rated lagging power factor.
REALAR(4) is the rated leading power factor.
REALAR(5) is the maximum reactive absorption in pu on Mbase.
Integer IERR

IERR = 2, exceeded maximum number of allowable reactive capability
records.
Invalid reactive capability status specified.
Integer NERR
PSS/E-29
3-27

3.11.2 Generation Reactive Capability Records by Subsystem

The following API is used to add or modify OPF generator reactive capability records within the
PSS/E working file, based upon a selected subsystem. This API is invoked through the subroutine
call:
AXOGRCNW(SID, ALL, INTGAR, REALAR, RVAL, IERR, NERR)

BAT_OPF_GEN_RCAP_SUBSYS
SID
ALL
REALAR(1)
REALAR(2)
REALAR(3) REALAR(4) REALAR(5) INTGAR(1)
RVAL(1)
RVAL(2)
RVAL(3)
RVAL(4)
RVAL(5)
where:
Integer SID
Integer ALL

Integer INTGAR(1)

INTGAR(1) is the reactive capability limit status:
INTGAR(1) = 1, in service, no reactive generation limits.
INTGAR(1) = 2, in service, inhibiting field increase.
INTGAR(1) = 3, in service, inhibiting field decrease.
INTGAR(1) = 4, in service, fixed Efd.
INTGAR(1) = 5, in service, apply reactive generation limits.
Real REALAR(5)

REALAR(1) is the direct-axis synchronous reactance in pu on Mbase.
REALAR(2) is the stator current limit in pu on Mbase.
REALAR(3) is the rated lagging power factor.
REALAR(4) is the rated leading power factor.
REALAR(5) is the maximum reactive absorption in pu on Mbase.
Integer RVAL(5)

as follows:
value of the direct-axis synchronous reactance.
value of the direct-axis synchronous reactance.
3-28
PSS/E-29


value of the stator current limit.
value of the stator current limit.
value of the rated lagging power factor.
value of the rated lagging power factor.
value of the rated leading power factor.
value of the rated leading power factor.
value of the maximum reactive absorption.
value of the maximum reactive absorption.
Integer IERR

IERR = 2, exceeded maximum number of allowable reactive capability
records.
Invalid reactive capability status specified.
Integer NERR
PSS/E-29
3-29

Generation Reserve Data
3.12 Generation Reserve Data

3.12.1 Individual Generation Reserve Records
The following API is used to add or modify individual generator reserve data records within the
PSS/E working file. The API is invoked through the subroutine call:
GENRSV_INDV_API(EIBUS, GENID, REALAR, IERR, NERR)

BAT_OPF_GENRSV_INDV
EIBUS GENID REALAR(1) REALAR(2)
where:
Integer EIBUS
Is the bus number.
Character*2 GENID
Real REALAR(2)
Is an array of two real elements whose value is as follows.

REALAR(1) is the unit ramp rate in MW/minute.
REALAR(2) is the unit capability in MW.
Integer IERR

IERR = 2, exceeded maximum number of allowable generator reserve
entries.
Integer NERR
3.12.2 Generator Reserve Records, by Subsystem

The following API is used to add or modify OPF generator reserve records within the PSS/E
working file, based upon a selected subsystem. This API is invoked through the subroutine call:
AXOGRSNW(SID, ALL, REALAR, RVAL, IERR, NERR)

BAT_OPF_GENRSV_SUBSYS
RVAL(1)
RVAL(2)
SID
ALL
REALAR(1) REALAR(2)
where:
Integer SID
3-30
PSS/E-29

Generation Reserve Data
Integer ALL

Real REALAR(2)

REALAR(1) is the unit ramp rate in MW/minute.
REALAR(2) is the unit capability in MW.
Integer RVAL(2)
Is an array of two integer elements. The value of each element is defined

as follows:
value of the unit ramp rate.
value of the unit ramp rate.
value of the unit capability.
value of the unit capability.
Integer IERR

IERR = 2, exceeded maximum number of allowable generator reserve
entries.
Integer NERR
PSS/E-29
3-31

Interface Flow Constraints
3.13 Interface Flow Constraints

3.13.1 Main Interface Flow Constraint Record
The following API is used to add or modify interface flow constraint records within the PSS/E
INTFLW_MAIN_API(IFID, LABL, INTGAR, REALAR, IERR, NERR)

BAT_OPF_INTFLW_MAIN
INTGAR(2) REALAR(3)
IFID LABL REALAR(1) REALAR(2) INTGAR(1)
where:
Integer IFID
Is the interface flow identifier.
Character*32 LABL
Is the interface flow description made up of, at most, 32 characters.
Integer INTGAR(2)
Is an array of two integer elements whose values are as follows:

INTGAR(1) is the interface flow type.
INTGAR(1) = 1, MW.
INTGAR(2) is the interface flow limit type.
Real REALAR(3)
Is an array of three real elements whose value is as follows.

REALAR(1) is the maximum interface flow, in physical units.
REALAR(2) is the minimum interface flow, in physical units.
Integer IERR

IERR = 1, exceeded maximum number of allowable interface flow constraint entries.
Maximum interface flow is less than the minimum interface flow.
Invalid flow type specified.
Invalid interface flow limit type specified.
Integer NERR
3-32
PSS/E-29

3.13.2 Remove all Participating Branches from an Interface

The following API is used to remove all interface branches associated with a particular interface
flow constraint within the PSS/E working file. The API is invoked through the subroutine call:
INTFLW_RESET_API(IFID, IERR, NERR)

BAT_OPF_INTFLW_RESET
IFID
where:
Integer IFID
Integer IERR

IERR = 1, invalid interface flow identifier specified.
Integer NERR
3.13.3 Adding Participating Branches

Two APIs and batch commands are available for adding participating branches, two-winding transformers or individual windings of a three-winding transformer.
The following API is used to add participating branches or two-winding transformers to a particular
interface flow constraint within the PSS/E working file. The API is invoked through the subroutine
call:
INTFLW_PART_BRN(IFID, EIBUS, EJBUS, CKTID, IERR, NERR)

BAT_OPF_INTFLW_BRN
IFID EIBUS EJBUS CKTID
The following API is used to add individual windings of a three-winding transformer to a particular
interface flow constraint within the PSS/E working file. The API is invoked through the subroutine
call:
INTFLW_PART_3WT(IFID, EIBUS, EJBUS, EKBUS, CKTID, IERR, NERR)

BAT_OPF_INTFLW_3WT
IFID EIBUS EJBUS EKBUS CKTID
where:
Integer IFID
Integer EIBUS

For a three-winding transformer, the value of EIBUS indicates the "from
bus" of the winding for which the flow constraint is being introduced.
PSS/E-29
3-33

Integer EJBUS
Integer EKBUS
Is the "third bus" number.
Character*2 CKTID
Integer IERR

IERR = 1, exceeded maximum number of allowable participating branch
entries.
IERR = 4, specified branch/three-winding transformer does not exist.
IERR = 5, specified branch/winding is already participating in the
interface.
Integer NERR
3-34
PSS/E-29

Linear Constraint Dependencies
3.14 Linear Constraint Dependencies

3.14.1 Main Linear Constraint Record
The following API is used to add or modify the header record of a OPF linear constraint dependency
record within the PSS/E working file. The API is invoked through the subroutine call:
LNCEQN_MAIN_API(IQID, LABL, REALAR, IERR, NERR)

BAT_OPF_LNCEQN_MAIN
IQID LABL REALAR(1) REALAR(2)
where:
Integer IQID
Is the linear constraint equation identification number.
Character*12 LABL
Is the linear constraint description made up of, at most, 12 characters.
Real REALAR(2)

REALAR(1) is the maximum constraint slack value.
REALAR(2) is the minimum constraint slack value.
Integer IERR

IERR = 1, exceeded maximum number of allowable linear constraint
dependency equations.
Maximum linear constraint slack is less than the minimum linear constraint slack.
Integer NERR
3.14.2 Remove all Participating Variables from Constraint Equation

The following API is used to remove all participating variables from a particular OPF linear constraint dependency equation within the PSS/E working file. The API is invoked through the
subroutine call:
LNCEQN_RESET_API(IQID, IERR, NERR)

BAT_OPF_LNCEQN_RESET
IQID
where:
Integer IQID
PSS/E-29
3-35

Integer IERR

IERR = 1, Invalid linear constraint identifier specified.
Integer NERR
3.14.3 Voltage Magnitude Variable

The following API is used to add or modify a participating bus voltage magnitude variable within
a particular OPF linear constraint dependency equation contained within the PSS/E working file.
LNCEQN_VMAG_API(IQID, EIBUS, REALAR, IERR, NERR)

BAT_OPF_LNCEQN_VMAG
IQID EIBUS REALAR(1)
where:
Integer IQID
Integer EIBUS
Is the bus number.
Real REALAR(1)

REALAR(1) is the value of the coefficient associated with the equation
variable.
Integer IERR

IERR = 1, specified linear constraint equation does not exist.
IERR = 2, exceeded maximum number of allowable participating equation
variables.
Integer NERR
3-36
PSS/E-29

3.14.4 Voltage Angle Variable

The following API is used to add or modify a participating bus voltage angle variable within a particular OPF linear constraint dependency equation contained within the PSS/E working file. The
API is invoked through the subroutine call:
LNCEQN_VANG_API(IQID, EIBUS, REALAR, IERR, NERR)

BAT_OPF_LNCEQN_VANG
where:
Integer IQID
Integer EIBUS
Is the bus number.
Real REALAR(1)

variable.
Integer IERR

variables.
Integer NERR
3.14.5 Active Power Dispatch Variable

The following API is used to add or modify a participating active power dispatch variable within
an OPF linear constraint dependency equation contained within the PSS/E working file. The API is
invoked through the subroutine call:
LNCEQN_PGEN_API(IQID, ITBL, REALAR, IERR, NERR)

BAT_OPF_LNCEQN_PGEN
IQID ITBL REALAR(1)
where:
Integer IQID
Integer ITBL
Is the active power dispatch table number.
Real REALAR(1)

variable.
PSS/E-29
3-37

Integer IERR

variables.
IERR = 3, invalid active power dispatch table number specified.
Integer NERR
3.14.6 Reactive Power Generation Variable

The following API is used to add or modify a participating reactive power generation variable
within an OPF linear constraint dependency equation contained within the PSS/E working file. The
API is invoked through the subroutine call:
LNCEQN_QGEN_API(IQID, EIBUS, GENID, REALAR, IERR, NERR)

BAT_OPF_LNCEQN_QGEN
IQID EIBUS GENID REALAR(1)
where:
Integer IQID
Integer EIBUS
Is the bus number.
Character*2 GENID
Real REALAR(1)

variable.
Integer IERR

variables.
IERR = 3, specified bus does not exist.
Integer NERR
3-38
PSS/E-29

3.14.7 Transformer Tap Variable

The following API is used to add or modify a participating two-winding or three-winding transformer tap variable within a particular OPF linear constraint dependency equation contained within
LNCEQN_TRAN_API(IQID, EIBUS, EJBUS, EKBUS, CKTID, REALAR, IERR,
NERR)

BAT_OPF_LNCEQN_TRAN
IQID EIBUS EJBUS EKBUS CKTID REALAR(1)
where:
Integer IQID
Integer EIBUS
Integer EJBUS
Integer EKBUS
Is the "third bus" number if a three-winding transformer is specified and

zero for a two-winding transformer.
Character*2 CKTID
Real REALAR(1)

variable.
Integer IERR

variables.
IERR = 4, specified branch/transformer does not exist.
IERR = 5, specified branch is not a transformer.
Integer NERR
3.14.8 Branch Flow Constraint Variable

The following API is used to add or modify a participating branch flow constraint variable within
an OPF linear constraint dependency equation contained within the PSS/E working file. The API is
LNCEQN_BRFLOW_API(IQID, EIBUS, EJBUS, EKBUS, CKTID, FLWID, REALAR,
IERR, NERR)
PSS/E-29
3-39


BAT_OPF_LNCEQN_BRFLW
REALAR(1)
IQID EIBUS EJBUS EKBUS CKTID FLWID
where:
Integer IQID
Integer EIBUS
Integer EJBUS
Integer EKBUS
Is the "third bus" number for a three-winding transformer and zero for a
two-winding transformer.
Character*2 CKTID
Character*1 FLWID
Is the branch flow identifier.
Real REALAR(1)

variable.
Integer IERR

variables.
IERR = 4, specified branch/transformer does not exist.
IERR = 5, specified branch flow does not exist.
Integer NERR
3.14.9 Interface Flow Constraint Variable

The following API is used to add or modify a participating interface flow variable within an OPF
linear constraint dependency equation contained within the PSS/E working file. The API is invoked
through the subroutine call:
LNCEQN_INTFLOW_API(IQID, ITBL, REALAR, IERR, NERR)

BAT_OPF_LNCEQN_INFLW
IQID ITBL REALAR(1)
where:
Integer IQID
3-40
PSS/E-29

Integer ITBL
Real REALAR(1)

variable.
Integer IERR

variables.
Integer NERR
3.14.10 Adjustable Bus Shunt Variable

The following API is used to add or modify a participating adjustable bus shunt variable within an
OPF linear constraint dependency equation contained within the PSS/E working file. The API is
LNCEQN_ADJVAR_API(IQID, EIBUS, SHNTID, REALAR, IERR, NERR)

BAT_OPF_LNCEQN_ADJVR
IQID EIBUS SHNTID REALAR(1)
where:
Integer IQID
Integer EIBUS
Is the bus number.
Character*1 SHNTID
Is the bus shunt identifier.
Real REALAR(1)

variable.
Integer IERR

variables.
IERR = 4, specified adjustable bus shunt does not exist.
Integer NERR
PSS/E-29
3-41

3.14.11 Switched Shunt Variable

The following API is used to add or modify a participating switched shunt variable within an OPF
linear constraint dependency equation contained within the PSS/E working file. The API is invoked
LNCEQN_SWSHUNT_API(IQID, EIBUS, REALAR, IERR, NERR)

BAT_OPF_LNCEQN_SWSHN
where:
Integer IQID
Integer EIBUS
Is the bus number.
Real REALAR(1)

variable.
Integer IERR

variables.
Integer NERR
3.14.12 Adjustable Bus Load Variable

The following API is used to add or modify a participating adjustable bus load variable within an
OPF linear constraint dependency equation contained within the PSS/E working file. The API is
LNCEQN_ADJLOAD_API(IQID, ITBL, REALAR, IERR, NERR)

BAT_OPF_LNCEQN_ADJLD
IQID ITBL REALAR(1)
where:
Integer IQID
Integer ITBL
Is the adjustable bus load table identifier.
3-42
PSS/E-29

Real REALAR(1)

variable.
Integer IERR

variables.
IERR = 3, specified adjustable bus load table does not exist.
Integer NERR
PSS/E-29
3-43

List OPF Data (LSTONW)
3.15 List OPF Data (LSTONW)

This API is used to produce a tabular report of the OPF working case data in a form suitable for data
documentation. The API is invoked through the subroutine call:
LSTONW(SID, ALL, OPT, VREV, IERR)

BAT_LSTO
SID
ALL
OPT
VREV
where:
Integer SID
Integer ALL

Integer OPT
Is the number corresponding to the category of OPF data that is to be

tabulated.
= 1, case summary
= 3, adjustable bus shunt data
= 5, bus load attributes tables
= 7, active power dispatch data
= 9, generator reactive capability
= 11, linear cost table data
= 13, polynomial and exponential cost
table data
= 15, branch flow data
= 17, linear constraint dependency data
= 2, bus data
= 4, bus load data
= 6, generator dispatch data
= 8, generation reserve data.
= 10, series compensation data
= 12, quadratic cost table data
= 14, period reserve data
= 16, interface flow data
= 21, full listing
Integer VREV
units.
Integer IERR

IERR = 3, no OPF data in the case.
3-44
PSS/E-29

OPF Solution (NOPFNW)
3.16 OPF Solution (NOPFNW)

This API is used to initiate the OPF solution process. Subsystems that have been specified will be
optimized to the objectives and tolerances specified, if a solution is achievable. The API is invoked
NOPFNW(SID, ALL, IERR, NERR)

BAT_NOPF
SID
ALL
where:
Integer SID
Is a valid bus subsystem ID. Valid subsystem IDs range from 0 to 3. A bus
subsystem must have been previously defined.
Integer ALL

Integer IERR

IERR = 1, SID is not valid.
Integer NERR
PSS/E-29
3-45

OPF Solution Options (OPTONW)
3.17 OPF Solution Options (OPTONW)

This API is used to set the OPF solution options data, including objectives and tolerances. The API
is invoked through the subroutine call:
OPTONW(SID, ALL, IARY, RARY, OPFILE, RCFILE, IERR, NERR)

BAT_OPTO
SID
OPFILE RCFILE
ALL
IARY(1) IARY(36)
RARY(1) RARY(19)
where:
Integer SID
Integer ALL

Integer IARY(36)
Is an array of 36 integers, which are defined as follows:

IARY(1) specifies the fuel cost objective.
IARY(1) = 0, do not employ minimize fuel cost objective.
IARY(1) = 1, employ the minimize fuel cost objective.
IARY(2) specifies the slack bus active power objective.
IARY(2) = 0, do not employ minimize slack bus active power objective.
IARY(2) = 1, employ the minimize slack bus active power objective.
IARY(3) specifies the reactive power slack objective.
IARY(3) = 0, do not employ the minimize reactive power slack objective.
IARY(3) = 1, employ the minimize reactive power slack objective.
IARY(4) specifies the active power loss objective.
IARY(4) = 0, do not employ the minimize active power loss objective.
IARY(4) = 1, employ the minimize active power loss objective.
IARY(5) specifies the reactive power loss objective.
IARY(5) = 0, do not employ the minimize reactive power loss objective.
IARY(5) = 1, employ the minimize reactive power loss objective.
IARY(6) specifies the series compensation objective.
IARY(6) = 0, do not employ series compensation minimization.
IARY(6) = 1, minimize series compensation.
IARY(7) specifies the var additions objective.
IARY(7) = 0, do not employ the minimize added var objective.
IARY(7) = 1, employ the minimize added var objective.
3-46
PSS/E-29

IARY(8) specifies the load adjustment objective.

IARY(8) = 0, do not employ the minimize load adjustment objective.
IARY(8) = 1, employ the minimize load adjustment objective.
IARY(9) specifies the interface flow objective.
IARY(9) = 0, do not employ the minimize interface flow objective.
IARY(9) = 1, employ the minimize interface flow objective.
IARY(10) specifies the reactive generation reserve objective.
IARY(10) = 0, do not employ the reactive generation reserve objective.
IARY(10) = 1, employ the reactive generation reserve objective.
IARY(11) specifies whether to apply the power flow mismatch tolerance
to the dual variable problem.
IARY(11) = 0, apply tolerance to the mismatch equation only.
IARY(11) = 1, apply tolerance to the entire equation.
IARY(12) specifies whether to clamp nonoptimized generators.
IARY(12) = 0, do not clamp nonoptimized generators.
IARY(12) = 1, clamp nonoptimized generators.
IARY(13) specifies whether to treat all transformers as nonoptimized.
(Not currently functional)
IARY(13) = 0, do not treat all transformers as nonoptimized.
IARY(13) = 1, treat all transformers as nonoptimized.
IARY(14) specifies whether to constrain interface flows.
IARY(14) = 0, do not constrain interface flows.
IARY(14) = 1, constrain interface flows.
IARY(15) specifies whether to employ automatic scaling of the objective.
IARY(15) = 0, do not employ automatic scaling.
IARY(15) = 1, employ automatic scaling.
IARY(16) specifies whether to regulate area interchange.
IARY(16) = 0, do not regulate area interchange.
IARY(16) = 1, regulate area interchange.
IARY(17) specifies whether to fix transformer tap ratio settings.
IARY(17) = 0, do not fix transformer tap ratio settings.
IARY(17) = 1, fix transformer tap ratio settings.
IARY(18) specifies whether to fix transformer phase shift angles.
IARY(18) = 0, do not fix transformer phase shift angles.
IARY(18) = 1, fix transformer phase shift angles.
PSS/E-29
3-47

IARY(19) specifies whether to fix switched shunt settings.

IARY(19) = 0, do not fix switched shunt settings.
IARY(19) = 1, fix switched shunt settings.
IARY(20) specifies whether to treat all generators as nonoptimized.
IARY(20) = 0, do not treat all generators as nonoptimized.
IARY(20) = 1, treat all generators as nonoptimized.
IARY(21) specifies whether to employ the generator scheduled voltage.
IARY(21) = 0, do not use generator scheduled voltage.
IARY(21) = 1, use generator scheduled voltage.
IARY(22) specifies whether to scale reactive generation limits on clamped
constraint equation.
IARY(22) = 0, do not scale reactive generation limits.
IARY(22) = 1, scale reactive generation limits.
IARY(23) specifies whether to round transformer tap settings.
IARY(23) = 0, do not round transformer tap settings.
IARY(23) = 1, round transformer tap settings.
IARY(24) specifies whether to round switched shunt settings.
IARY(24) = 0, do not round switched shunts.
IARY(24) = 1, round switched shunts.
IARY(25) specifies whether to limit the step taken during solution.
IARY(25) = 0, do not limit the step.
IARY(25) = 1, limit the step taken.
IARY(26) specifies whether to output an optimization log file.
IARY(26) = 0, do not output an optimization log file.
IARY(26) = 1, output an optimization log file.
IARY(27) specifies whether to print out a detailed listing of Lagrange
multipliers.
IARY(27) = 0, do not print details.
IARY(27) = 1, print Lagrange multipliers.
IARY(28) specifies whether to produce a PSS/E raw data change file.
IARY(28) = 0, do not produce an RDCH file.
IARY(28) = 1, produce an RDCH file.
IARY(29) specifies whether to save the OPF solution option settings to the
OPF Options File, PSSOPF.OPT.
IARY(29) = 0, do not save settings.
IARY(29) = 1, save settings to PSSOPF.OPT.
3-48
PSS/E-29

IARY(30) indicates whether the program should open limits to ensure a

feasible initial condition.
IARY(30) = 0, do not have the program open the limits for a feasible initial
condition.
IARY(30) = 1, have the program open the limits for a feasible initial
condition.
IARY(31) specifies whether to impose emergency bus voltage limits or
normal bus voltage limits.
IARY(31) = 0, do not utilize the emergency bus voltage limits (normal
voltage limits used instead).
IARY(31) = 1, impose emergency bus voltage limits.
IARY(32) specifies whether to impose emergency branch flow limits or
normal branch flow limits.
IARY(32) = 0, do not utilize the emergency branch flow limits (normal
branch flow limits used instead).
IARY(32) = 1, impose emergency branch flow limits.
IARY(33) specifies whether to include transformer adjustment data in the
RDCH file (if one is produced according to the setting of IARY(29)).
IARY(33) = 0, do not include transformer adjustment data.
IARY(33) = 1, include transformer adjustment data.
IARY(34) specifies the maximum iteration limit (corresponds to ITMXN
of the load flow solution parameters).
IARY(35) specifies the "bad" iteration coarse limit.
IARY(36) specifies the "bad" iteration fine limit.
Real RARY(19)
PSS/E-29
Is an array of 19 real elements, which are defined as follows:

RARY(1) specifies the initial barrier function coefficient.
RARY(2) specifies the final barrier function coefficient.
RARY(3) specifies the step length blow-up tolerance.
RARY(4) specifies the minimum clamp tolerance value.
RARY(5) specifies the maximum clamp tolerance value.
RARY(6) specifies the clamp equation decay factor.
RARY(7) specifies the cost coefficient for the active power loss objective.
RARY(8) specifies the cost coefficient for the reactive power loss
objective.
RARY(9) specifies the penalty value for load flow controls.
RARY(10) specifies the cost coefficient for the interface flow objective.
RARY(11) specifies the cost coefficient for the reactive generation reserve
objective.
RARY(12) specifies the penalty value for fixed voltage.
3-49

RARY(13) specifies the lambda tolerance.

RARY(14) specifies the minimum amount to open up tap settings by.
RARY(15) specifies the maximum amount to open up tap settings by.
RARY(16) specifies the amount to shift the interior point by during
solution.
RARY(17) specifies the step length taken for the barrier method.
RARY(18) specifies the tolerance value used to determine which bus
shunts get added to the RDCH file as switched shunts (if an RDCH file is
produced according to IARY(28) and the minimize added vars objective is
employed according to IARY(7)).
RARY(19) specifies the solution convergence tolerance, in MVA (corresponds to TOLN of the load flow solution parameters).
Filename OPFILE
Is the name of the Optimization Log File which will be produced if

IARY(26) is set to 1. It is a good idea to specify the filename within quotes.
Filename RCFILE
Is the name of the PTI Read Change Data File which will be produced if
IARY(28) is set to 1. It is a good idea to specify the filename within quotes.
Integer IERR

IERR = 3, IARY or RARY data error.
Integer NERR
3-50
PSS/E-29

Period Reserve Constraints
3.18 Period Reserve Constraints

3.18.1 Main Period Reserve Constraint
The API is used to add or modify a period reserve constraint record within the PSS/E working file.
PERRSV_MAIN_API(RSVID, INTGAR, REALAR, IERR, NERR)

BAT_OPF_PERRSV_MAIN
RSVID REALAR(1) REALAR(2) INTGAR(1)
where:
Integer RSVID
Is the period reserve identifier (1 through 15).
Integer INTGAR(1)

INTGAR(1) is the status of the period reserve constraint.
Real REALAR(2)

REALAR(1) is the reserve limit, in MW.
REALAR(2) is the period, in minutes.
Integer IERR

IERR = 1, invalid period reserve identifier specified.
Invalid period reserve status specified.
Integer NERR
3.18.2 Remove all Participating Reserve Units

The following API is used to remove all generation reserve units associated with a particular period
reserve constraint within the PSS/E working file. The API is invoked through the subroutine call:
PERRSV_RESET_API(RSVID, IERR, NERR)

BAT_OPF_PERRSV_RESET
RSVID
where:
Integer RSVID
PSS/E-29
3-51

Period Reserve Constraints
Integer IERR

Integer NERR
3.18.3 Add Participating Reserve Unit

The following API is used to add participating generation reserve units to a particular period reserve
constraint within the PSS/E working file. The API is invoked through the subroutine call:
PERRSV_PART_GEN(RSVID, EIBUS, GENID, IERR, NERR)

BAT_OPF_PERRSV_GEN
RSVID EIBUS GENID
where:
Integer RSVID
Integer EIBUS
Is the bus number.
Character*2 GENID
Integer IERR

IERR = 4, specified unit does not have any generator reserve data defined.
IERR = 5, specified unit is already participating in the reserve constraint.
IERR = 6, exceeded maximum number of allowable participating units.
Integer NERR
3-52
PSS/E-29

Read Optimal Power Flow Data File
3.19 Read Optimal Power Flow Data File

This API is used to read in an Optimal Power Flow Data File. The API is invoked through the subroutine call:
ROPFNW(RFILE, IERR, NERR)

BAT_ROPF
RFILE
where:
Character RFILE*260 Is the Optimal Power Flow Data File name, or "1" if input is comping
directly from the terminal or Response file.
Integer IERR
PSS/E-29

IERR = 0, no error.
IERR = 1, problem encountered while opening file.
3-53

Two-terminal dc Lines
3.20 Two-terminal dc Lines

The following API is used to modify two-terminal dc line constraint records within the PSS/E
OPF_2TERMDC_API(IDC, REALAR, IERR, NERR)

BAT_OPF_2TERM_DC
REALAR(4)
IDC
REALAR(1)
REALAR(2)
REALAR(3)
where:
Integer IDC
Is the two-terminal dc line number.
Real REALAR(4)
Is an array of four real elements whose value is as follows.

REALAR(1) is the dc maximum flow limit, in physical units.
REALAR(2) is the dc minimum flow limit, in physical units.
REALAR(3) is the dc maximum voltage, in per unit.
REALAR(4) is the dc minimum voltage, in per unit.
Integer IERR

IERR = 1, invalid two-terminal dc line specified.
dc maximum flow limit is less than the minimum.
dc maximum voltage limit is less than the minimum
Integer NERR
3-54
PSS/E-29

Write OPF Data File (RWOPNW)
3.21 Write OPF Data File (RWOPNW)

This API is used to write out the OPF data contained in the working case in the form of an Optimal
Power Flow Data File. The API is invoked through the subroutine call:
RWOPNW(SID, ALL, STATUS, OUT, OFILE, IERR)

BAT_RWOP
OUT OFILE
SID
ALL
STATUS(1)
STATUS(2)
STATUS(3)
STATUS(4)
where:
Integer SID
Integer ALL
Is the "all" buses or selected buses subsystem flag.

Integer STATUS(4)
Is an array of four elements. They are used to control output options. A

value of 0 means the option is not enabled. A value of 1 means the option
is enabled. They are as follows.
STATUS(4), include subsystem tie lines.
Integer OUT


Integer IERR
PSS/E-29

IERR = 0, no error.
IERR = 5, no OPF data in the case.
3-55
3-56
PSS/E-29
CHAPTER
4
DYNAMICS SIMULATION APIS
This chapter describes the APIs used in PSS/E Dynamics Simulations.
4.1 CHSBNW
This API is used to select the simulation variables that are to monitored during dynamic simulation
runs on a subsystem basis. The API is invoked by the use of the statement:
CHSBNW(SID, ALL, STATUS, IERR)
or:
BAT_CHSB
STATUS(5)
SID ALL
STATUS(6)
STATUS(1)
STATUS(2)
STATUS(3)
STATUS(4)
where:
Integer SID
Is a valid area, bus, or zone subsystem ID. Valid area, bus, or zone subsystem IDs range from 0 to 3. An area, bus, or zone subsystem must have
been previously defined.
Integer ALL

Integer STATUS(6)
Is an array of six elements. The value of each is as follows.

STATUS(1) is the starting channel index, or -1 for next available.
STATUS(2) is the starting VAR index, or -1 for next available.
STATUS(3) is the starting ICON index, or -1 for next available.
STATUS(4), used to indicate mode of operation.
STATUS(4) = 1, machine, bus, load, branch quantities by bus subsystem.
STATUS(4) = 2, tie quantity by area.
STATUS(4) = 3, tie quantity by zone.
STATUS(4) = 4, power totals for area subsystem.
STATUS(4) = 5, power totals for zone subsystems.
STATUS(4) = 6, power totals for owner subsystems.
PSS/E-29
4-1

CHSBNW
STATUS(4) = 7, power totals for all buses.

STATUS(4) = 8, machine angle statistics.
STATUS(5), quantity code. If STATUS(4) = 2 or 3
STATUS(5) = 1, flow (P).
STATUS(5) = 2, flow (P and Q).
STATUS(5) = 3, flow (MVA).
STATUS(5) = 4, apparent impedance (R and X).
STATUS(5), quantity code. If STATUS(4) = 1.
STATUS(5) = 1, ANGLE.
STATUS(5) = 2, PELEC.
STATUS(5) = 3, QELEC
STATUS(5) = 4, ETERM.
STATUS(5) = 5, EFD.
STATUS(5) = 6, PMECH.
STATUS(5) = 7, SPEED.
STATUS(5) = 8, AXDIFD.
STATUS(5) = 9, ECOMP.
STATUS(5) = 10, VOTHSG.
STATUS(5) = 11, VREF.
STATUS(5) = 12, BSFREQ.
STATUS(5) = 13, VOLT.
STATUS(5) = 14, voltage and angle
STATUS(5) = 15, flow (P).
STATUS(5) = 16, flow (P and Q).
STATUS(5) = 17, flow (MVA).
STATUS(5) = 18, apparent impedance (R and X).
STATUS(5) = 21, ITERM.
STATUS(5) = 22, machine apparent impedance
STATUS(5) = 23, VUEL.
STATUS(5) = 24, VOEL.
STATUS(5) = 25, PLOAD.
STATUS(5) = 26, QLOAD.
STATUS(6), determines what to do with out-of-service equipment.
STATUS(6) = 0, omit out-of-service equipment.
STATUS(6) = 1, include out-of-service equipment.
Integer IERR
4-2

IERR = 2, bad starting channel, VAR or ICON index.
IERR = 3, STATUS(4) is in error.
PSS/E-29

CHSBNW

IERR = 6, reached end of ICON, VAR, or channel array.
IERR = 7, angle statistics already in channels.
PSS/E-29
4-3

DOCUNW
4.2 DOCUNW
This API is used to produce a tabulation of the data associated with equipment models referenced
in the users simulation setup. The API is invoked by the use of the statement:
DOCUNW(SID, ALL, STATUS, IERR)
or:
BAT_DOCU
SID
ALL
STATUS(1)
STATUS(2)
STATUS(3)
where:
Integer SID
Integer ALL

Integer STATUS(3)
Is a three-element array.
STATUS(1), processing mode.
STATUS(1) = 0, reporting mode.
STATUS(1) = 1, data checking mode.
STATUS(2), models to output.
STATUS(2) = 0, output all CONEC models.
STATUS(2) = 1, output all CONET models.
STATUS(2) = 2, output all CHAN models.
STATUS(2) = 3, output models by subsystem.
STATUS(3), is the type of model whose data are to be output.
= 1, all models
= 2, all plant models
= 3, generator models
= 4, compensator models
= 5, stabilizer models
= 6, minimum excitation limiter models
= 7, maximum excitation limiter models = 8, excitation system models
= 9, turbine governor models
= 10, load characteristic models
= 11, load relay models
= 12, line relay models
= 13, CONEC models
= 14, CONET models
= 15, CHAN models
Integer IERR
4-4

IERR = 0, no error.
PSS/E-29

DYDANW
4.3 DYDANW
This API is used to write out dynamics model data in the form of a Dynamics Data Input file. The
DYDANW(SID, ALL, STATUS, OUT, OFILE, IERR)
or:
BAT_DYDA
SID
ALL
STATUS(1)
STATUS(2)
STATUS(3)
OUT
OFILE
where:
Integer SID
Integer ALL

Integer STATUS(3)
STATUS(1), models to output.
STATUS(1) = 0, output all CONEC models.
STATUS(1) = 1, output all CONET models.
STATUS(1) = 2, output models by subsystem.
STATUS(2), is the type of model whose data is to be output.
= 1, all models
= 2, all plant models
= 3, generator models
= 4, compensator models
= 5, stabilizer models
= 6, minimum excitation limiter models
= 7, maximum excitation limiter models = 8, excitation system models
= 9, turbine governor models
= 10, load characteristic models
= 11, load relay models
= 12, line relay models
= 13, CONEC models
= 14, CONET models
STATUS(3), load model output option

STATUS(3) = 0, selected subsystem models
STATUS(3) = 1, all subsystem models
Integer OUT
PSS/E-29

4-5

DYDANW
Character OFILE*260 Is the working case data output file.

Integer IERR
4-6

IERR = 0, no error.
PSS/E-29

RSTRNW
4.4 RSTRNW
This API is used to read in a Dynamics snapshot file. The API is invoked by the use of the statement:
RSTRNW(SFILE, IERR)
or:
BAT_RSTR
SFILE
where:
Character SFILE*260
Is the snapshot file.
Integer IERR

IERR = 0, no error.
IERR = 2, error reading from SFILE.
PSS/E-29
4-7

SNAPNW
4.5 SNAPNW
This API is used to save a Dynamics snapshot file. The API is invoked by the use of the statement:
SNAPNW(STATUS, SFILE, IERR)
or:
BAT_SNAP
SFILE
STATUS(1) STATUS(2) STATUS(3) STATUS(4) STATUS(5)
where:
Integer STATUS(5)
Is a five-element array.
STATUS(1), number of CONs, or -1 for 1 through "next available -1".
STATUS(1), number of STATEs, or -1 for 1 through "next available -1".
STATUS(3), number of VARs, or -1 for 1 through "next available -1".
STATUS(4), number of ICONs, or -1 for 1 through "next available -1".
STATUS(5), next available output channel.
Character SFILE*260
Is the Dynamics snapshot. If SFILE is "*", SNAPNW will attempt to save

the Dynamics snapshot file with the last name used. If none exists,
SNAPNW will return an IERR value.
Integer IERR

IERR = 3, error writing to SFILE.
4-8
PSS/E-29

LDLIST
4.6 LDLIST
This API is used to list load models in dynamics working memory. The API is invoked by the use
of the statement:
LDLIST(SID, ALL, STATUS, IERR)
or:
BAT_LDLIST
SID
ALL
STATUS(1)
STATUS(2)
where:
Integer SID
Integer ALL

Integer STATUS(2)
STATUS(1), output mode.
STATUS(1) = 0, active and bypassed models.
STATUS(1) = 1, active models only.
STATUS(1) = 2, bypassed models only
STATUS(2), load model reporting option.
STATUS(2) = 0, models connected to loads.
STATUS(2) = 1, loads connected to model.
Integer IERR
PSS/E-29

IERR = 0, no error.
4-9

LDMOD_STATUS
4.7 LDMOD_STATUS
This API is used to change the status of the models at all loads at which the model is applied. The
LDMOD_STATUS(MTYPE, IBUS, LMODID, LTYPE, IST, IERR)
or:
BAT_LDMOD_STATUS
MTYPE
IBUS
LMODID
LTYPE IST
where:
Integer MTYPE
Is the model type.

MTYPE = 0, bus models.
MTYPE = 1, owner models.
MTYPE = 2, zone models.
MTYPE = 3, area models.
MTYPE = 4, all models.
Integer IBUS
Is the external bus, area, owner, or zone number. Not used when
MTYPE = 4.
Character LMODID *2 Is the two-character load model ID.

Integer LTYPE
Is the load model type.

LTYPE = 1, load characteristic model.
LTYPE = 2, load relay model.
Integer IST
Is the new desired status.

IST = 0, out of service.
IST = 1, in service.
Integer IERR

IERR = 0, no error.
IERR = 1, model not found.
IERR = 2, invalid LTYPE.
IERR = 3, invalid MTYPE.
IERR = 4, invalid IBUS.
IERR = 5, invalid status.
4-10
PSS/E-29

LDMOD_STATUS2
4.8 LDMOD_STATUS2
This API is used to change the status of a model for an individual load. The API is invoked by the
LDMOD_STATUS2(IBUS, LDID, LTYPE, IST, IERR)
or:
BAT_LDMOD_STATUS2 IBUS
LDID
LTYPE IST
where:
Integer IBUS
Character LDID *2
Is the two-character load ID.
Integer LTYPE

Integer IST

Integer IERR

IERR = 0, no error.
IERR = 1, load or model not found.
PSS/E-29
4-11

LDMOD_REMOVE
4.9 LDMOD_REMOVE
This API is used to remove a load model from dynamics working memory. The API is invoked by
LDMOD_REMOVE(MTYPE, IBUS, LMODID, LTYPE, IERR)
or:
BAT_LDMOD_REMOVE
MTYPE
IBUS
LMODID
LTYPE
where:
Integer MTYPE
Is the model type.

Integer IBUS
MTYPE = 4.
Character LMODID *2 Is the two-character load model ID.

Integer LTYPE

Integer IERR

IERR = 0, no error.
IERR = 3, invalid MTYPE.
IERR = 4, invalid IBUS.
4-12
PSS/E-29

LDMOD_UNCONNECTED
4.10 LDMOD_UNCONNECTED
This API is used to list or remove unconnected load models from dynamics working memory. The
LDMOD_UNCONNECTED(OPT, IERR)
or:
BAT_LDMOD_UNCONNECTED
OPT
where:
Integer OPT
OPT = 0, list unconnected load models.

OPT = 1, remove unconnected load models.
Integer IERR

IERR = 0, no error.
PSS/E-29
4-13

LDMOD_PACK
4.11 LDMOD_PACK
This API is used to remove unused load model connection entries and compress remaining entries
and remove unused load model allocation entries and compress remaining entries. The API is
LDMOD_PACK
or:
BAT_LDMOD_PACK
4-14
PSS/E-29

LDMOD_USER
4.12 LDMOD_USER
This API is used to list user-written load model definitions and to remove unused user-written load
model definitions from the user model definition tables. The API is invoked by use of the statement:
LDMOD_USER(OPT, IERR)
or:
BAT_LDMOD_USER OPT
where:
Integer OPT
Is the action code.

OPT = 0, list user-written load model definitions.
OPT = 1, remove unused user-written load model definitions.
Integer IERR

IERR = 0, no error.
PSS/E-29
4-15

CHANGE_LDMOD_DATA
4.13 CHANGE_LDMOD_DATA
This API is used to change a data value for a load model. The API is invoked by use of the
statement:
CHANGE_LDMOD_DATA(IBUS, LMODID, MTYPE, LTYPE, MNAME, J, RDATA, I,
IDATA, CHDATA IERR)
or:
BAT_CHANGE_LDMOD_DATA IBUS LMODID MTYPE LTYPE MNAME J RDATA I
IDATA CHDATA
where:
Integer IBUS
MTYPE = 4.
Character LMODID*2
Is the two-character load model ID.
Integer MTYPE
Is the model type.

Integer LTYPE

Character MDNAME*6
Is the six-character model name.
Integer J
Is the CON to change (J would be 1, J + 1 would be 2, etc.).
Real RDATA
Is the new CON value.
Integer I
Is the ICON to change (I would be 1, I + 1 would be 2, etc.).
Integer IDATA
Is the new ICON value.
Character CHDATA*2
Is the new two-character ICON value. If entering an integer, this value

should be set to either $$ or .
Integer IERR

IERR = 0, no error.
IERR = 1, model type or subsystems number or load ID not found.
IERR = 2, invalid model name.
IERR = 3, invalid real or integer data item to change.
4-16
PSS/E-29

ADD_LOAD_MODEL
4.14 ADD_LOAD_MODEL
This API is used for adding a load model. The API is invoked by use of the statement:
ADD_LOAD_MODEL(IBUS, LMODID, MTYPE, LTYPE, MDNAME, NICN, IDATA,
CHDATA, NCON, RDATA, IERR)
or:
BAT_ADD_LOAD_MODEL IBUS LMODID MTYPE LTYPE MDNAME NICN IDATA
CHDATA NCON RDATA
where:
Integer IBUS
MTYPE = 4.
Character LMODID*2
Is the two-character load model ID.
Integer MTYPE
Is the model type.

Integer LTYPE

Character MDNAME*6
Integer NICN
Is the number of ICONs in the model.
Integer IDATA(NICN)
Are the ICON data.
Character CHDATA(NICN)*2 Are the character ICON data. When an integer value is input for
an ICON, CHDATA () should be set to either $$ or .
Integer NCON
Is the number of CONs in the model.
Real RDATA(NCON)
Are the CON data.
PSS/E-29
4-17

ADD_LOAD_MODEL
Integer IERR
4-18

IERR = 0, no error.
IERR = 1, load not found.
IERR = 2, load model tables full.
IERR = 3, invalid subsystem type.
IERR = 4, invalid model type.
IERR = 6, model name and model type do not match CONs.
IERR = 7, invalid number of CONs or ICONs.
IERR = 8, data arrays full.
PSS/E-29

MLSTNW
4.15 MLSTNW
This API is used to list plant models in dynamics working memory. The API is invoked by use of
the statement:
MLSTNW(SID, ALL, STATUS, IERR)
or:
BAT_MLST SID ALL STATUS(1) STATUS(2) STATUS(3)
where:
Integer SID
Is a valid subsystem ID. Valid subsystem IDs range from 0 to 3. A bus subsystem must have been previously defined.
Integer ALL

Integer STATUS(3)
STATUS(1) = 0, list unconnected models.
STATUS(1) = 1, list only connected models.
STATUS(2) = 0, active and by passed models.
STATUS(2) = 1, active models only.
STATUS(2) = 2, by passed models only.
STATUS(3) = 1, all plant models.
STATUS(3) = 2, generator models.
STATUS(3) = 3, compensator models.
STATUS(3) = 4, stabilizer models.
STATUS(3) = 5, minimum excitation models.
STATUS(3) = 6, maximum excitation models.
STATUS(3) = 7, exciters.
STATUS(3) = 8, governors.
Integer IERR
PSS/E-29

IERR = 0, no error.
4-19

CHANGE_PLMOD_DATA
4.16 CHANGE_PLMOD_DATA
This API is used to change a data value for a plant model. The API is invoked by use of the
statement:
CHANGE_PLMOD_DATA(IBUS, ID, MTYPE, NAME, J, RDATA, I, IDATA,
CHDATA, IERR)
or:
BAT_CHANGE_PLMOD_DATA IBUS ID MTYPE NAME J RDATA I IDATA CHDATA
where:
Integer IBUS
Is the external plant bus number.
Character ID*2
Is the two-character plant ID.
Integer MTYPE
Is the model type.

MTYPE = 1, generator model.
MTYPE = 2, compensator model.
MTYPE = 3, stabilizer model.
MTYPE = 4, minimum excitation model.
MTYPE = 5, maximum excitation model.
MTYPE = 6, exciter model.
MTYPE = 7, governor model.
Character NAME*6
Integer J
Real RDATA
Integer I
Integer IDATA
Character CHDATA*2 Is the new two-character ICON value. If entering an integer, this value
should be set to either $$ or .
Integer IERR
4-20
Is the error code.

IERR = 0, no error.
IERR = 5, invalid CON or ICON position.
PSS/E-29

ADD_PLANT_MODEL
4.17 ADD_PLANT_MODEL
This API is used for adding a plant model. The API is invoked by use of the statement:
ADD_PLANT_MODEL(IBUS, ID, MTYPE, NAME, IBUS2, ID2, NICN, IDATA,
CHDATA, NCON, RDATA, IERR)
or:
BAT_ADD_PLANT_MODEL IBUS ID MTYPE NAME IBUS2 ID2 NICN IDATA CHDATA
NCON RDATA
where:
Integer IBUS
Character ID*2
Is the two-character plant ID.
Integer MTYPE
Is the model type.

Character NAME*6
Integer IBUS
Is the second machine external bus number or 0 for a single machine

model.
Character ID2*2
Is the two-character ID of the second machine or if a single machine

model.
Integer NICN
Integer IDATA(NICN)
Are the ICON data.
Character CHDATA(NICN)Are the character ICON data. When an integer value is input for an
ICON, CHDATA (that integer) should be set to either $$ or .
Integer NCON
Integer DATA(NCON)
Are the CON data.
PSS/E-29
4-21

ADD_PLANT_MODEL
Integer IERR
4-22

IERR = 0, no error.
IERR = 2, plant model tables full.
IERR = 3, plant model tables corrupted.
IERR = 6, model name and type dont match.
IERR = 7, invalid number of ICONs or CONs.
IERR = 9, invalid specification of second machine.
PSS/E-29

PLMOD_STATUS
4.18 PLMOD_STATUS
This API is used to change the status for an individual plant model. The API is invoked by use of
the statement:
PLMOD_STATUS(IBUS, ID, MTYPE, IST, IERR)
or:
BAT_PLMOD_STATUS IBUS ID MTYPE IST
where:
Integer IBUS
Character ID*2
Is the two-character machine ID.
Integer MTYPE
Is the model type.

Integer IST
Is the new model status.

IST = 0, model out of service.
IST = 1, model in service.
Integer IERR

IERR = 0, no error.
PSS/E-29
4-23

PLMOD_REMOVE
4.19 PLMOD_REMOVE
This API is used to remove a plant model from the dynamics working memory. The API is invoked
by use of the statement:
PLMOD_REMOVE(IBUS, ID, MTYPE, IERR)
or:
BAT_PLMOD_REMOVE IBUS ID MTYPE
where:
Integer IBUS
Character ID*2
Is the two-character machine ID.
Integer MTYPE
Is the model type.

Integer IERR
Is the error code.

IERR = 0, no error.
4-24
PSS/E-29

PLMOD_UNCONNECTED
4.20 PLMOD_UNCONNECTED
This API is used to list or remove unconnected plant models from the dynamics working memory.
The API is invoked by use of the statement:
PLMOD_UNCONNECTED(OPT, IERR)
or:
BAT_PLMOD_UNCONNECTED OPT
where:
Integer OPT
OPT = 0, list unconnected plant models.

OPT = 1, remove unconnected plant models.
Integer IERR

IERR = 0, no error.
PSS/E-29
4-25

PLMOD_PACK
4.21 PLMOD_PACK
This API is used to remove unused plant model connection entries and compress remaining entries
and remove unused plant model allocation entries and compress remaining entries. The API is
invoked by use of the statement:
PLMOD_PACK
or:
BAT_PLMOD_PACK
4-26
PSS/E-29

PLMOD_USER
4.22 PLMOD_USER
This API is used to list user-written plant model definitions and to remove unused user-written plant
model definitions from the user model definition tables. The API is invoked by use of the statement:
PLMOD_USER(OPT, IERR)
or:
BAT_PLMOD_USER OPT
where:
Integer OPT
Is the action code.

OPT = 0, list user-written plant model definitions.
OPT = 1, remove unused user-written plant model definitions.
Integer IERR
Is the error code.

IERR = 0, no error.
PSS/E-29
4-27

PLMOD_CONSISTENCY
4.23 PLMOD_CONSISTENCY
This API is used to check consistency of plant related models. The API is invoked by use of the
statement:
PLMOD_CONSISTENCY
or:
BAT_PLMOD_CONSISTENCY
4-28
PSS/E-29

RLLIST
4.24 RLLIST
This API is used to list line related models in the dynamics working arrays. The API is invoked by
RLLIST(SID, ALL, STATUS, IERR)
or:
BAT_RLLIST SID ALL STATUS(1) STATUS(2)
where:
Integer SID
Integer ALL

Integer STATUS(2)
STATUS(2) = 0, active and by passed models.
Integer IERR
Is the error code.

IERR = 0, no error.
IERR = 1, ALL or SID is in error.
PSS/E-29
4-29

CHANGE_RLMOD_DATA
4.25 CHANGE_RLMOD_DATA
This API is used to change a data value for a line related model. The API is invoked by use of the
statement:
CHANGE_RLMOD_DATA(IBUS, JBUS, ID, RS, NAME, J, RDATA, I, IDATA,
CHDATA, IERR)
or:
BAT_CHANGE_RLMOD_DATA IBUS JBUS ID RS NAME J RDATA I IDATA CHDATA
where:
Integer IBUS
Is the external "from" bus number.
Integer JBUS
Is the external "to" bus number.
Character ID*2
Is the two-character branch ID.
Integer RS
Is the relay slot, either 1 or 2.
Character NAME*6
Integer J
Real RDATA
Integer I
Integer IDATA
Character CHDATA*2 Is the new two-character ICON value. If entering an integer ICON, this
value should be set to either $$ or .
Integer IERR
4-30
Is the error code.

IERR = 0, no error.
IERR = 2, invalid relay slot.
IERR = 5, invalid CON or ICON.
PSS/E-29

ADD_RELAY_MODEL
4.26 ADD_RELAY_MODEL
This API is used for adding a line relay. The API is invoked by use of the statement:
ADD_RELAY_MODEL(IBUS, JBUS, ID, RS, NAME, NICN, IDATA, CHDATA,
NCON, RDATA, IERR)
or:
BAT_ADD_RELAY_MODEL IBUS JBUS ID RS NAME NICN IDATA CHDATA NCON
RDATA IERR
where:
Integer IBUS
Integer JBUS
Character ID*2
Integer RS
Character NAME*6
Integer NICN
Integer IDATA(NICN)
Are the ICON data.
Character CHDATA(NICN)*2 Are the character ICON data. When an integer value is input for
an ICON, CHDATA () should be set to either $$ or .
Integer NCON
Real RDATA(NCON)
Are the CON data.
Integer IERR
Is the error code.

IERR = 0, no error.
IERR = 3, line relay tables full.
IERR = 5, invalid number of CONs or ICONs.
IERR = 7, tables corrupted.
PSS/E-29
4-31

RLMOD_STATUS
4.27 RLMOD_STATUS
This API is used to change the status of a line related relay model. The API is invoked by use of the
statement:
RLMOD_STATUS(IBUS, JBUS, ID, RS, IST, IERR)
or:
BAT_RLMOD_STATUS IBUS JBUS ID RS IST
where:
Integer IBUS
Integer JBUS
Character ID*2
Integer RS
Integer IST

Integer IERR
Is the error code.

IERR = 0, no error.
4-32
PSS/E-29

RLMOD_REMOVE
4.28 RLMOD_REMOVE
This API is used to remove a line relay model from the dynamics working memory. The API is
RLMOD_REMOVE(IBUS, JBUS, ID, RS, IERR)
or:
BAT_RLMOD_REMOVE IBUS JBUS ID RS
where:
Integer IBUS
Integer JBUS
Character ID*2
Integer RS
Integer IERR
Is the error code.

IERR = 0, no error.
IERR = 1, branch or relay not found.
PSS/E-29
4-33

RLMOD_UNCONNECTED
4.29 RLMOD_UNCONNECTED
This API is used to list or remove unconnected line relay models. The API is invoked by use of the
statement:
RLMOD_UNCONNECTED(OPT, IERR)
or:
BAT_RLMOD_UNCONNECTED OPT
where:
Integer OPT
OPT = 0, list unconnected line relays.

OPT = 1, remove unconnected line relays.
Integer IERR
Is the error code.

IERR = 0, no error.
4-34
PSS/E-29

RLMOD_PACK
4.30 RLMOD_PACK
This API is used to remove unused line relay model connection entries and compress remaining
entries and remove unused line relay model allocation entries and compress remaining entries. The
API is invoked by use of the statement:
RLMOD_PACK
or:
BAT_RLMOD_PACK
PSS/E-29
4-35

RLMOD_USER
4.31 RLMOD_USER
This API is used to list user-written line relay model definitions and to remove unused user-written
line relay model definitions from the user model definition tables. The API is invoked by use of the
statement:
RLMOD_USER(OPT, IERR)
or:
BAT_RLMOD_USER OPT
where:
Integer OPT
Is the action code.

OPT = 0, list user-written line relay definitions.
OPT = 1, remove unused user-written line relay definitions.
Integer IERR
Is the error code.

IERR = 0, no error.
4-36
PSS/E-29

SET_NETFRQ
4.32 SET_NETFRQ
This API is used to set or obtain the settings of simulation option. The API is invoked by use of the
statement:
SET_NETFRQ(STATUS, ICODE, IERR)
or:
BAT_SET_NETFRQ STATUS
where:
Integer STATUS
Is the integer action code.

STATUS = 1, use network frequency dependence.
STATUS = 0, do not use network frequency dependence.
Integer ICODE
Is the action to be taken.

ICODE = 0, set the option.
ICODE = 1, find current setting.
Integer IERR
Is the error code.

IERR = 0, no error.
IERR = 1, cannot set in mid-simulation.
PSS/E-29
4-37

SET_OSSCAN
4.33 SET_OSSCAN
This API is used to set or obtain the settings of an out of setup scanning option. The API is invoked
by use of the statement:
SET_OSSCAN(STATUS, TRIP, ICODE)
or:
BAT_SET_OSSCAN STATUS TRIP
where:
Integer STATUS
Is the action code.

STATUS = 1, scan for out of setup.
STATUS = 0, do not scan.
Integer TRIP
Is the action you want relay to take.

TRIP = 1, trip out of setup circuits.
TRIP = 0, monitor only.
Integer ICODE
Is how API is used.

ICODE = 0, set the option.
ICODE = 1, get current setting.
4-38
PSS/E-29

SET_RELANG
4.34 SET_RELANG
This API is used for setting the relative angle simulation option. The API is invoked by use of the
statement:
SET_RELANG(SWITCH, IBUSEX, ID, ICODE, IERR)
or
BAT_SET_RELANG SWITCH IBUSEX ID ICODE
Integer SWITCH
Is the enable/disable code.

SWITCH = 1, compute relative angles.
SWITCH = 0, absolute angles.
Integer IBUSEX
Is the external bus number for reference angle.

IBUSEX = 0, use system average angle.
IBUSEX = -1, use system weighted average angle.
Character ID*2
Is the machine ID.
Integer ICODE
Is the set/fetch switch.

ICODE = 0, set option.
ICODE = 1, fetch current settings.
Ingeter IERR
Is the error code.

IERR = 0, no error.
IERR = 1, invalid BUS/ID or code.
PSS/E-29
4-39

SET_RELSCN
4.35 SET_RELSCN
This API is used to set or obtain the settings of a generic relay scanning function. The API is
SET_RELSCN(STATUS, ICODE)
or:
BAT_SET_RELSCN STATUS
where:
Integer STATUS
Is the action code.

STATUS = 1, scan all branches.
STATUS = 0, do not scan.
Integer ICODE
Is how API is used.

ICODE = 0, set scanning.
ICODE = 1, get current setting.
4-40
PSS/E-29

SET_VLTSCN
4.36 SET_VLTSCN
This API is used to set or obtain the current setting of voltage scanning. The API is invoked by use
of the statement:
SET_VLTSCN(STATUS, VHI, VLO, ICODE, IERR)
or:
BAT_SET_VLTSCN STATUS VHI VLO
where:
Integer STATUS
Is the action code.

STATUS = 1, do voltage scanning.
STATUS = 0, no scanning.
Real VHI
Is the high voltage threshold.
Real VLO
Is the low voltage threshold.
Integer ICODE
Is how API is used.

ICODE = 0, set scanning.
ICODE = 1, get current setting and thresholds.
Integer IERR
Is the error code.

IERR = 0, no error.
IERR = 1, invalid thresholds.
PSS/E-29
4-41
4-42
PSS/E-29
CHAPTER
5
SUBSYSTEM DEFINITION APIS
5.1 System Initialization Definition APIs

The following subsections describe the APIs used to define area, bus, owner, and zone subsystems.
Their appropriate use, and associated APIs, are also described.
5.1.1 SBSINIT
This API is used to initialize the area, bus, owner, and zone subsystem definition APIs. The API is
SBSINIT
or:
BAT_SBSINIT
PSS/E-29
5-1

Area Subsystem Definition APIs
5.2 Area Subsystem Definition APIs

The following APIs are used to create, set, and delete area subsystems.
5.2.1 SBSACREATE
This API is used to create an area subsystem. The API is invoked by the use of the statement:
SBSACREATE(SID, IERR)
or:
BAT_SBSACREATE
SID
where:
Integer SID
Is a valid area subsystem ID. Valid area subsystem IDs range from 0 to 3.
Integer IERR

5.2.2 SBSASET
This API is used to set an area subsystem. Once the subsystem is set, the application can query the
selected area subsystem by the use of the area subsystem selection APIs described in Chapter 6. The
SBSASET(SID, NUM, AREAS, IERR)
or:
BAT_ASYS
SID
NUM
AREAS(1) AREAS(NUM)
where:
Integer SID
Integer NUM
Is the number of areas to set.
Integer AREAS
Is an array of NUM elements that contains the areas to set.
Integer IERR

5-2
PSS/E-29

Area Subsystem Definition APIs
5.2.3 SBSADELETE
This API is used to delete a previously created area subsystem. The API is invoked by the use of
the statement:
SBSADELETE(SID, IERR)
or:
BAT_SBSADELETE
SID
where:
Integer SID
Integer IERR

PSS/E-29
5-3

Bus Subsystem Definition APIs
5.3 Bus Subsystem Definition APIs

The following APIs are used to create, set, and delete bus subsystems.
5.3.1 SBSBCREATE
This API is used to create a bus subsystem. The API is invoked by the use of the statement:
SBSBCREATE(SID, IERR)
or:
BAT_SBSBCREATE
SID
where:
Integer SID
Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.
Integer IERR

5.3.2 SBSBSET
This API is used to set a bus subsystem. Once the subsystem is set, the application can query the
selected bus subsystem by the use of the bus subsystem selection APIs described in Chapter 6. The
SBSBSET(SID, USEKV, BASEKV, NUMAREA, AREAS, NUMBUS, BUSES,
NUMOWNER, OWNERS, NUMZONE, ZONES, IERR)
or:
BAT_BSYS
SID USEKV BASEKV(1) BASEKV(2) NUMAREA AREAS(1)
AREAS(NUMAREA) NUMBUS BUSES(1) BUSES(NUMBUS) NUMOWNER
NUMZONE ZONES(1)
OWNERS(1) OWNERS(NUMOWNER)
ZONES(NUMZONE)
where:
Integer SID
Integer USEKV
USEKV = 0, do not use BASEKV values.

USEKV = 1, use BASEKV values.
Real BASEKV(2)

BASEKV(1) is the minimum basekV limit.
BASEKV(2) is the maximum basekV limit.
Integer NUMAREA
5-4
PSS/E-29

Integer AREAS
Is an array of NUMAREA elements that contains the areas to set.
Integer NUMBUS
Is the number of buses to set.
Integer BUSES
Is an array of NUMBUS elements that contains the buses to set.
Integer NUMOWNER Is the number of owners to set.

Integer OWNERS
Is an array of NUMOWNER elements that contains the owners to set.
Integer NUMZONE
Is the number of zones to set.
Integer ZONES
Is an array of NUMZONE elements that contains the zones to set.
Integer IERR

5.3.3 SBSBSETA
This API is used to set a bus subsystem using bus names. Once the subsystem is set, the application
can query the selected bus subsystem by the use of the bus subsystem selection APIs described in
Chapter 6. The API is invoked by the use of the statement:
SBSBSETA(SID, USEKV, BASEKV, NUMAREA, AREAS, NUMBUS, BUSES,
BUS_LEN, NUMOWNER, OWNERS, NUMZONE, ZONES, IERR)
or:
BAT_BSYS
SID USEKV BASEKV(1) BASEKV(2) NUMAREA AREAS(1)
AREAS(NUMAREA) NUMBUS busname(1) busname(NUMBUS) BUS_LEN
NUMOWNER OWNERS(1) OWNERS(NUMOWNER)
NUMZONE ZONES(1)
ZONES(NUMZONE)
where:
Integer SID
Integer USEKV
USEKV = 0, do not use BASEKV values.

USEKV = 1, use BASEKV values.
Real BASEKV(2)

BASEKV(1) is the minimum basekV limit.
BASEKV(2) is the maximum basekV limit.
Integer NUMAREA
Integer AREAS
Is an array of NUMAREA elements that contains the areas to set.
Integer NUMBUS
Is the number of buses to set.
character BUSES
Is an array of NUMBUS elements that contains the 14-character extended

bus names to set.
PSS/E-29
5-5

Integer BUSLEN
Is the length of a single element of the character array BUSES, e.g.,

BUSES(1).
Integer NUMOWNER Is the number of owners to set.

Integer OWNERS
Is an array of NUMOWNER elements that contains the owners to set.
Integer NUMZONE
Integer ZONES
Is an array of NUMZONE elements that contains the zones to set.
Integer IERR

5.3.4 SBSBDELETE
This API is used to delete a previously created bus subsystem. The API is invoked by the use of the
statement:
SBSBDELETE(SID, IERR)
or:
BAT_SBSBDELETE
SID
where:
Integer SID
Integer IERR

5.3.5 SBSBUSDSP
This API is used to enable or disable the updating of the bus subsystem selector dialogs during calls
to SBSBSET or SBSBSETA. The API is invoked by the use of the statement:
SBSBUSDSP(OPT, IERR)
or:
BAT_SBSBUSDSP
OPT
where:
Integer OPT
OPT = 0, disable update of bus subsystem selector dialogs.

OPT = 1, enable and perform update of bus subsystem selector dialogs.
Integer IERR

5-6
PSS/E-29

5.3.6 SBSBSMEM
This API is used to "memorize" the current selected bus subsystem into a bus subsystem file. This
bus subsystem file may then be "recalled" at a later time to restore the selected bus subsystem. The
SBSBSMEM(SID, SFILE, IERR)
or:
BAT_BSYSMEM
SID
SFILE
where:
Integer SID
Is a valid bus subsystem id. Valid bus subsystem ids range from 0-3.
Character SFILE*260
Is the bus subsystem file name.
Integer IERR

5.3.7 SBSBSRCL
This API is used to "recall" a selected bus subsystem saved in a bus subsystem file. The API is
SBSBSRCL(SID, SFILE, IERR)
or:
BAT_BSYSRCL
SID
SFILE
where:
Integer SID
Is a valid bus subsystem id. Valid bus subsystem ids range from 0-3.
Character SFILE*260
Is the bus subsystem file name.
Integer IERR

IERR = 3, not a valid bus subsystem file
IERR = 4, items in bus subsystem file not found in working case
PSS/E-29
5-7

Owner Subsystem Definition APIs
5.4 Owner Subsystem Definition APIs

The following APIs are used to create, set, and delete owner subsystems.
5.4.1 SBSOCREATE
This API is used to create an owner subsystem. The API is invoked by the use of the statement:
SBSOCREATE(SID, IERR)
or:
BAT_SBSOCREATE
SID
where:
Integer SID
Is a valid owner subsystem ID. Valid owner subsystem IDs range from
0 to 3.
Integer IERR

5.4.2 SBSOSET
This API is used to set an owner subsystem. Once the subsystem is set, the application can query
the selected owner subsystem by the use of the owner subsystem selection APIs described in
Chapter 6. The API is invoked by the use of the statement:
SBSOSET(SID, NUM, OWNERS, IERR)
or:
BAT_OSYS
SID
NUM
OWNERS(1) OWNERS(NUM)
where:
Integer SID
0 to 3.
Integer NUM
Is the number of owners to set.
Integer OWNERS
Is an array of NUM elements that contains the owners to set.
Integer IERR

5-8
PSS/E-29

Owner Subsystem Definition APIs
5.4.3 SBSODELETE
This API is used to delete a previously created owner subsystem. The API is invoked by the use of
the statement:
SBSODELETE(SID, IERR)
or:
BAT_SBSODELETE
SID
where:
Integer SID
0 to 3.
Integer IERR

PSS/E-29
5-9

Zone Subsystem Definition APIs
5.5 Zone Subsystem Definition APIs

The following APIs are used to create, set, and delete zone subsystems.
5.5.1 SBSZCREATE
This API is used to create an zone subsystem. The API is invoked by the use of the statement:
SBSZCREATE(SID, IERR)
or:
BAT_SBSZCREATE
SID
where:
Integer SID
Is a valid zone subsystem ID. Valid zone subsystem IDs range from 0 to 3.
Integer IERR

5.5.2 SBSZSET
This API is used to set an zone subsystem. Once the subsystem is set, the application can query the
selected zone subsystem by the use of the zone subsystem selection APIs described in Chapter 6.
SBSZSET(SID, NUM, ZONES, IERR)
or:
BAT_ZSYS
SID
NUM
ZONES(1) ZONES(NUM)
where:
Integer SID
Integer NUM
Integer ZONES
Is an array of NUM elements that contains the zones to set.
Integer IERR

5-10
PSS/E-29

Zone Subsystem Definition APIs
5.5.3 SBSZDELETE
This API is used to delete a previously created zone subsystem. The API is invoked by the use of
the statement:
SBSZDELETE(SID, IERR)
or:
BAT_SBSZDELETE
SID
where:
Integer SID
Integer IERR

PSS/E-29
5-11
5-12
PSS/E-29
CHAPTER
6
SUBSYSTEM SELECTION APIS
This chapter describes the APIs used to process and return selected area, bus, owner, and zone subsystems to the application. The subsystem selectors are used to select areas, buses, owners, and
zones for processing by the application. Their appropriate use, and associated APIs, are described
in the following subsections.
6.1 Area Subsystem Selection APIs

The area subsystem selector, as shown in Figure 6-1, is used to select areas for applications that only
require areas to operate. The areas selected in the area subsystem selector are not selected in the bus
subsystem selector. Up to four area subsystems maybe defined. They are numbered from 0 to 3.
They can, if desired, be used to predefine area subsystems and then used appropriately whenever
required.
Figure 6-1. Area Subsystem Selector
PSS/E-29
6-1

Area Subsystem Selection APIs
6.1.1 SBSADEF
This API is used to determine if an area subsystem has been defined. The API is invoked by the use
of the statement:
SBSADEF(SID, INIT)
where:
Integer SID
Logical INIT
Is returned as the existence flag.

INIT = .FALSE., area subsystem has not been defined.
INIT = .TRUE., area subsystem has been defined.
6.1.2 SBSALINIT
This API is used to initialize the subsystem to return areas. This call must be matched with a call to
SBSALTERM. The API is invoked by the use of the statement:
SBSALINIT(SID, ALL, INIT)
where:
Integer SID
An area subsystem must have been previously defined.
Integer ALL
Is the all areas or selected subsystem flag.

Integer INIT
Is the value to initialize the system at. Normally initialized with a value of 0.
6.1.3 SBSALAREA
This API is used to loop through all selected areas. SBSALINIT must have been called previously
to initialize the looping. The API is invoked by the use of the statement:
SBSALAREA(SID, AREA)
where:
Integer SID
Integer AREA
Is returned as an area number.

AREA > 0, area number.
AREA = 0, all valid selected areas have been returned.
6-2
PSS/E-29

Area Subsystem Selection APIs
6.1.4 SBSALTERM
This API is called after all valid area numbers have been returned. Commonly called when
AREA = 0 is returned in a call to SBSALAREA. This call must match each call to SBSALINIT.
SBSALTERM(SID)
where:
Integer SID
6.1.5 SBSAVLA
This API is used to determine if an area is valid in the selected area subsystem. This API does not
require any initialization before being invoked. This API makes no judgment on whether the area
is actually in use or not, only on whether the supplied area is in the selected areas list in the area
subsystem selector. The API is invoked by the use of the statement:
SBSAVLA(SID, AREA, EXIST)
where:
Integer SID
Integer AREA
Is the area to test.
Logical EXIST

EXIST = .FALSE., area is not selected in the area subsystem.
EXIST = .TRUE., area is selected in the area subsystem.
PSS/E-29
6-3

Bus Subsystem Selection APIs
6.2 Bus Subsystem Selection APIs

The bus subsystem selector, as shown in Figure 6-2, is used to select buses for applications that
require buses to operate. Up to four bus subsystems maybe defined. They are numbered from 0 to
3. They can, if desired, be used to predefine bus subsystems and then used appropriately whenever
required.
Figure 6-2. Bus Subsystem Selector
6.2.1 SBSBDEF
This API is used to determine if a bus subsystem has been defined. The API is invoked by the use
of the statement:
SBSBDEF(SID, INIT)
where:
Integer SID
Logical INIT

INIT = .FALSE., bus subsystem has not been defined.
INIT = .TRUE., bus subsystem has been defined.
6-4
PSS/E-29

6.2.2 SBSBLAREANB
This API is used to loop through selected areas, zones, and owners and return them. The application
that calls this routine is interested in the area, zone, and owners selected, and will determine which
buses are selected as a result on its own. SBSBLAINIT must have been called previously to initialize the looping. The API is invoked by the use of the statement:
SBSBLAREANB(SID, AREA, ZONE, OWNER, FLAG)
where:
Integer SID
A bus subsystem must have been previously defined.
Integer AREA
Is returned as the current selected area number.
Integer ZONE
Is returned as the current selected zone number.
Integer OWNER
Is returned as the current selected owner number.
Integer FLAG
Is returned as status flag.

FLAG > 0, AREA, ZONE, OWNER contain valid selections.
FLAG = 0, all valid selections have been returned.
6.2.3 SBSBLBUSNB
This API is used maintain the structure of existing code where other calls are to SBSBLAREANB,
SBSBLZONENB, and SBSBLOWNERNB. This routine returns a FLAG = 1 on the first call, and
FLAG = 0 on subsequent calls. SBSBLAINIT must have been called previously to initialize the
looping. The API is invoked by the use of the statement:
SBSBLBUSNB(SID, FLAG)
where:
Integer SID
Integer FLAG
Is returned as a status flag.

FLAG = 1, returned on first call.
FLAG = 0, returned on subsequent calls.
6.2.4 SBSBLZONENB
This API is used to loop through selected zones, and owners and return them. The application that
calls this routine is interested in the zone and owners selected, and will determine which buses are
selected as a result on its own. SBSBLAINIT must have been called previously to initialize the
looping. The API is invoked by the use of the statement:
SBSBLZONENB(SID, ZONE, OWNER, FLAG)
PSS/E-29
6-5

where:
Integer SID
Integer ZONE
Is returned as the current selected zone number.
Integer OWNER
Integer FLAG

FLAG > 0, ZONE, OWNER contain valid selections.
6.2.5 SBSBLOWNERNB
This API is used to loop through selected owners and return them. The application that calls this
routine is interested in the owners selected, and will determine which buses are selected as a result
on its own. SBSBLAINIT must have been called previously to initialize the looping. The API is
SBSBLOWNERNB(SID, OWNER, FLAG)
where:
Integer SID
Integer OWNER
Integer FLAG

FLAG > 0, OWNER contain valid selection.
6.2.6 SBSVLAREA
This API is used to determine if an area is valid in the selected bus subsystem. This API does not
require any initialization before being invoked. This API makes no judgment on whether the area
is actually in use or not, only on whether the supplied area is in the selected areas list in the bus
SBSVLAREA(SID, AREA, EXIST)
where:
Integer SID
Integer AREA
Is the area to test.
Logical EXIST

EXIST = .FALSE., area is not selected in the bus subsystem.
EXIST = .TRUE., area is selected in the bus subsystem.
6-6
PSS/E-29

6.2.7 SBSVLBUS
This API is used to determine if a bus sequence number is valid in the selected bus subsystem. This
API does not require any initialization before being invoked. The API is invoked by the use of the
statement:
SBSVLBUS(SID, SEQNUM, OPT, EXIST)
where:
Integer SID
Integer SEQNUM
Is the bus sequence number to test.
Integer OPT
Is used to control ANDing of the bus sequence number with area, owner,
zone, and base KV selections.
OPT = 0, no ANDing, will return EXIST = .TRUE. if bus sequence
number was selected.
OPT = 1, use ANDing, will return EXIST = .TRUE. if bus sequence
number was selected and survived the ANDing.
Logical EXIST

EXIST = .FALSE., bus sequence number is not selected in the bus
subsystem.
EXIST = .TRUE., bus sequence number is selected in the bus subsystem.
6.2.8 SBSVLLOD
This API is used to determine if a load bus sequence number is valid in the selected bus subsystem.
This routines tests the bus number and base KV and the load area, owner, and zone values against
those selected in the subsystem selector. This API does not require any initialization before being
invoked. The API is invoked by the use of the statement:
SBSVLLOD(SID, SEQNUM, OPT, EXIST, AREA, ZONE,OWNER)
where:
Integer SID
Integer SEQNUM
Is the load bus sequence number to test.
Integer OPT
Is used to control ANDing of load bus sequence number and area/owner/

zone entries with area, owner, zone, and base KV selections.
OPT = 0, no ANDing, will return EXIST = .TRUE. if load bus sequence
number was selected.
OPT = 1, use ANDing, will return EXIST = .TRUE. if load bus sequence
number was selected and survived the ANDing.
PSS/E-29
6-7

Logical EXIST

EXIST = .FALSE., load bus sequence number is not selected in the bus
subsystem.
EXIST = .TRUE., load bus sequence number is selected in the bus
subsystem.
Integer AREA
Is the area number to use in testing the load bus sequence number.
Integer ZONE
Is the zone number to use in testing the load bus sequence number.
Integer OWNER
Is the owner number to use in testing the load bus sequence number.
6.2.9 SBSVLMCBR
This API is used to determine if the machines and branches connected to a bus are valid in the
selected bus subsystem. The area, zone, and base kV values are taken from the bus. The ownership
values are passed as an array to the API. This API does not require any initialization before being
invoked. The API is invoked by the use of the statement:
SBSVLNUM(SID, SEQNUM, OPT, EXIST, NOWN, OWNARY)
where:
Integer SID
Integer SEQNUM
Is the bus sequence number to test.
Integer OPT
Is used to control ANDing of bus number and area/zone entries with

area, owner, zone, and base kV selections.
OPT = 0, no ANDing, will return EXIST = .TRUE. if bus number was
selected.
OPT = 1, use ANDing, will return EXIST = .TRUE. if bus number was
selected and survived the ANDing.
Logical EXIST

EXIST = .FALSE., bus number is not selected in the bus subsystem.
EXIST = .TRUE., bus number is selected in the bus subsystem.
Integer NOWN
Is the number of owners of the machine or branch.
Integer OWNARY
Is an array of dimension NOWN of owners.
6-8
PSS/E-29

6.2.10 SBSVLNUM
This API is used to determine if a bus number is valid in the selected bus subsystem. This API does
not require any initialization before being invoked. The API is invoked by the use of the statement:
SBSVLNUM(SID, BNUM, OPT, EXIST, AREA, ZONE, OWNER, BSKV)
where:
Integer SID
Integer BNUM
Is the bus number to test.
Integer OPT
Is used to control ANDing of bus number and area/zone entries with

area, owner, zone, and base kV selections.
OPT = 0, no ANDing, will return EXIST = .TRUE. if bus number was
selected.
OPT = 1, use ANDing, will return EXIST = .TRUE. if bus number was
selected and survived the ANDing.
Logical EXIST

EXIST = .FALSE., bus number is not selected in the bus subsystem.
EXIST = .TRUE., bus number is selected in the bus subsystem.
Integer AREA
Is the area number to use in testing the bus number.
Integer ZONE
Is the zone number to use in testing the bus number.
Integer OWNER
Is the owner number to use in testing the bus number.
Real BSKV
Is the base kV value to use in testing the bus number.
6.2.11 SBSVLOWNER
This API is used to determine if a owner is valid in the selected bus subsystem. This API does not
require any initialization before being invoked. This API makes no judgment on whether the owner
is actually in use or not, only on whether the supplied owner is in the selected owners list in the bus
SBSVLOWNER(SID, OWNER, EXIST)
where:
Integer SID
Integer OWNER
Is the owner to test.
Logical EXIST

EXIST = .FALSE., owner is not selected in the bus subsystem.
EXIST = .TRUE., owner is selected in the bus subsystem.
PSS/E-29
6-9

6.2.12 SBSVLZONE
This API is used to determine if a zone is valid in the selected bus subsystem. This API does not
require any initialization before being invoked. This API makes no judgment on whether the zone
is actually in use or not, only on whether the supplied zone is in the selected zones list in the bus
SBSVLZONE(SID, ZONE, EXIST)
where:
Integer SID
Integer ZONE
Is the zone to test.
Logical EXIST

EXIST = .FALSE., zone is not selected in the bus subsystem.
EXIST = .TRUE., zone is selected in the bus subsystem.
6.2.13 SBSBLAINIT
This API is used to initialize the subsystem to return all buses for every returned area/owner/
zone/base kV. This API is used to return buses when additional testing is need on each bus. For
every area/owner/zone/base kV selected in the bus subsystem selector, every bus is returned. It is
left to the application to determine if the bus returned is really valid for the current area/owner/
zone/base kV. This call must be matched with a call to SBSBLTERM. The API is invoked by the
SBSBLAINIT(SID, ALL, BYAREA, BYBUS, BYKV, BYOWNR, BYZONE)
where:
Integer SID
Integer ALL
Is the all buses or selected subsystem flag. Is used to control return of

BYxxxx variables.
ALL = 1, all buses being processed. BYAREA, BYBUS, BYKV,
BYOWNR, and BYZONE are all returned as FALSE.
ALL = 0, only selected buses being processed.
Logical BYAREA
Is TRUE when areas have been selected.
Logical BYBUS
Is TRUE when buses have been selected.
Logical BYKV
Is TRUE when a base kV range has been selected.
Logical BYOWNR
Is TRUE when owners have been selected.
Logical BYZONE
Is TRUE when zones have been selected.
6-10
PSS/E-29

6.2.14 SBSBLINIT
This API is used to initialize the subsystem to return buses. This call must be matched with a call
to SBSBLTERM. The API is invoked by the use of the statement:
SBSBLINIT(SID, ALL, OPT, BYAREA, BYBUS, BYKV, BYOWNR, BYZONE)
where:
Integer SID
Integer ALL
Is the all buses or selected subsystem flag.

ALL = 1, process all buses. BYAREA, BYBUS, BYKV, BYOWNR, and
BYZONE are all returned as FALSE. Subsequent calls of SBSBLAREA,
SBSBLZONE, and SBSBLOWNER are not allowed. Looping must either
be done by SBSBLBUS or specific looping in the application itself.
Integer OPT
Is used to setup ANDing of selected buses with area, owner, zone, and
base kV selections.
OPT = 0, no ANDing, return all selected buses.
OPT = 1, use ANDing, return only those selected buses that survive the
ANDing.
Logical BYAREA
Logical BYBUS
Logical BYKV
Logical BYOWNR
Logical BYZONE
6.2.15 SBSBLAREA
This API is used to loop through all selected buses and return bus sequence numbers in reports that
are organized by area, then zone, then owner, and then bus. SBSBLINIT must have been called previously to initialize the looping. Sequence numbers are returned in alphabetic or numeric order
depending on the value of bus output option. The API is invoked by the use of the statement:
SBSBLAREA(SID, AREA, ZONE, OWNER, SEQNUM)
where:
Integer SID
Integer AREA
Is returned as the current area number for the bus sequence number.
PSS/E-29
6-11

Integer ZONE
Is returned as the current zone number for the bus sequence number.
Integer OWNER
Is returned as the current owner number for the bus sequence number.
Integer SEQNUM
Is returned as a valid bus sequence number.

SEQNUM > 0, bus sequence number.
SEQNUM = 0, all valid selected buses have been returned.
6.2.16 SBSBLBUS
are organized by bus. SBSBLINIT must have been called previously to initialize the looping.
Sequence numbers are returned in alphabetic or numeric order depending on the value of bus output
option. The API is invoked by the use of the statement:
SBSBLBUS(SID, SEQNUM)
where:
Integer SID
Integer SEQNUM

6.2.17 SBSBLZONE
are organized by zone, then owner, and then bus. SBSBLINIT must have been called previously to
initialize the looping. Sequence numbers are returned in alphabetic or numeric order depending on
the value of bus output option. The API is invoked by the use of the statement:
SBSBLZONE(SID, ZONE, OWNER, SEQNUM)
where:
Integer SID
Integer ZONE
Is returned as the current zone number for the bus sequence number.
Integer OWNER
Integer SEQNUM

6-12
PSS/E-29

6.2.18 SBSBLOWNER
are organized by owner, and then bus. SBSBLINIT must have been called previously to initialize
the looping. Sequence numbers are returned in alphabetic or numeric order depending on the value
of bus output option. The API is invoked by the use of the statement:
SBSBLOWNER(SID, OWNER, SEQNUM)
where:
Integer SID
Integer OWNER
Integer SEQNUM

6.2.19 SBSBLTERM
This API is called after all valid bus sequence numbers have been returned. Commonly called when
SEQNUM = 0 is returned in a call to SBSBLBUS, SBSBLAREA, SBSBLZONE, or
SBSBLOWNER. This call must match each call to SBSBLINIT. The API is invoked by the use of
the statement:
SBSBLTERM(SID)
where:
Integer SID
6.2.20 SBSGTBKV
This API is used to return the selected Base kV range. The API is invoked by the use of the
statement:
SBSGTBKV(SID, KVMIN, KVMAX)
where:
Integer SID
Real KVMIN
Is returned as the selected base kV minimum.
Real KVMAX
Is returned as the selected base kV maximum.
PSS/E-29
6-13

6.2.21 SBSGTFLG
This API is used to return the flags indicating how buses have been selected. The API is invoked
SBSGTFLG(SID, ALL, BYAREA, BYBUS, BYKV, BYOWNR, BYZONE)
where:
Integer SID
Integer ALL
Is the all buses or selected subsystem flag.

ALL = 1, all buses are selected. BYAREA, BYBUS, BYKV, BYOWNR,
and BYZONE are all returned as FALSE.
ALL = 0, individual selections have been made.
Logical BYAREA
Logical BYBUS
Logical BYKV
Logical BYOWNR
Logical BYZONE
6-14
PSS/E-29

Owner Subsystem Selection APIs
6.3 Owner Subsystem Selection APIs

The owner subsystem selector, as shown in Figure 6-3, is used to select owners for applications that
only require owners to operate. The owners selected in the owner subsystem selector are not
selected in the bus subsystem selector. Up to four owner subsystems maybe defined. They are numbered from 0 to 3. They can, if desired, be used to predefine owner subsystems and then used
appropriately whenever required.
Figure 6-3. Owner Subsystem Selector
6.3.1 SBSODEF
This API is used to determine if a owner subsystem has been defined. The API is invoked by the
SBSZDEF(SID, INIT)
where:
Integer SID
0 to 3.
Logical INIT

INIT = .FALSE., owner subsystem has not been defined.
INIT = .TRUE., owner subsystem has been defined.
PSS/E-29
6-15

6.3.2 SBSOLINIT
This API is used to initialize the subsystem to return owners. This call must be matched with a call
to SBSOLTERM. The API is invoked by the use of the statement:
SBSOLINIT(SID, ALL, INIT)
where:
Integer SID
0 to 3. A owner subsystem must have been previously defined.
Integer ALL
Is the all owners or selected subsystem flag.

ALL = 1, process all owners.
ALL = 0, process only selected owners.
Integer INIT
6.3.3 SBSOLOWNER
This API is used to loop through all selected owners. SBSOLINIT must have been called previously
SBSOLOWNERS(SID, OWNER)
where:
Integer SID
Integer OWNER
Is returned as an owner number.

OWNER > 0, owner number.
OWNER = 0, all valid selected owners have been returned.
6.3.4 SBSOLTERM
This API is called after all valid owner numbers have been returned. Commonly called when
OWNER = 0 is returned in a call to SBSOLOWNER. This call must match each call to SBSOLINIT. The API is invoked by the use of the statement:
SBSOLTERM(SID)
where:
Integer SID
6-16
PSS/E-29

6.3.5 SBSOVLO
This API is used to determine if an owner is valid in the selected owner subsystem. This API does
not require any initialization before being invoked. This API makes no judgment on whether the
owner is actually in use or not, only on whether the supplied owner is in the selected owners list in
the owner subsystem selector. The API is invoked by the use of the statement:
SBSOVLO(SID, OWNER, EXIST)
where:
Integer SID
0 to 3.
Integer OWNER
Is the owner to test.
Logical EXIST

EXIST = .FALSE., owner is not selected in the owner subsystem.
EXIST = .TRUE., owner is selected in the owner subsystem.
PSS/E-29
6-17

Zone Subsystem Selection APIs
6.4 Zone Subsystem Selection APIs

The zone subsystem selector, as shown in Figure 6-4, is used to select zones for applications that
only require zones to operate. The zones selected in the zone subsystem selector are not selected in
the bus subsystem selector. Up to four zone subsystems maybe defined. They are numbered from
0 to 3. They can, if desired, be used to predefine zone subsystems and then used appropriately
whenever required.
Figure 6-4. Zone Subsystem Selector
6.4.1 SBSZDEF
This API is used to determine if a zone subsystem has been defined. The API is invoked by the use
of the statement:
SBSZDEF(SID, INIT)
where:
Integer SID
Logical INIT

INIT = .FALSE., zone subsystem has not been defined.
INIT = .TRUE., zone subsystem has been defined.
6-18
PSS/E-29

6.4.2 SBSZLINIT
This API is used to initialize the subsystem to return zones. This call must be matched with a call
to SBSZLTERM. The API is invoked by the use of the statement:
SBSZLINIT(SID, ALL, INIT)
where:
Integer SID
A zone subsystem must have been previously defined.
Integer ALL
Is the all zones or selected subsystem flag.

Integer INIT
6.4.3 SBSZLZONE
This API is used to loop through all selected zones. SBSZLINIT must have been called previously
SBSZLZONE(SID, ZONE)
where:
Integer SID
Integer ZONE
Is returned as an zone number.

ZONE > 0, zone number.
ZONE = 0, all valid selected zones have been returned.
6.4.4 SBSZLTERM
This API is called after all valid zone numbers have been returned. Commonly called when
ZONE = 0 is returned in a call to SBSZLZONE. This call must match each call to SBSZLINIT. The
SBSZLTERM(SID)
where:
Integer SID
PSS/E-29
6-19

6.4.5 SBSZVLZ
This API is used to determine if a zone is valid in the selected zone subsystem. This API does not
require any initialization before being invoked. This API makes no judgment on whether the zone
is actually in use or not, only on whether the supplied zone is in the selected zones list in the zone
SBSZVLZ(SID, ZONE, EXIST)
where:
Integer SID
Integer ZONE
Is the zone to test.
Logical EXIST

EXIST = .FALSE., zone is not selected in the zone subsystem.
EXIST = .TRUE., zone is selected in the zone subsystem.
6-20
PSS/E-29

Miscellaneous Subsystem APIs
6.5 Miscellaneous Subsystem APIs

The following APIs are used to refresh the area, bus, and zone subsystem selectors. A call to the
area refresh API will update area displays in the area subsystem selector, as well as the area selection and area filtering sections of the bus subsystem selector. The same thing occurs during a call to
the zone refresh API.
6.5.1 SBSRBDAL
This API is used to refresh the area displays in the area and bus subsystem selectors. The API is
SBSRBDAL(SID)
where:
Integer SID
Is a valid subsystem ID. Valid subsystem IDs range from 0 to 3.
6.5.2 SBSRBDBL
This API is used to refresh the bus display in the bus subsystem selectors. The API is invoked by
SBSRBDBL(SID)
where:
Integer SID
6.5.3 SBSRBDOL
This API is used to refresh the owner displays in the owner and bus subsystem selectors. The API
SBSRBDOL(SID)
where:
Integer SID
6.5.4 SBSRBDZL
This API is used to refresh the zone displays in the zone and bus subsystem selectors. The API is
SBSRBDZL(SID)
where:
Integer SID
PSS/E-29
6-21
6-22
PSS/E-29

Batch

Uploaded by

Copyright:

Available Formats

Batch

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Batch

Uploaded by

Copyright:

Available Formats

What are some of the main APIs discussed in the document?

What are some of the main APIs discussed in the document?

What information is refreshed through subsystem selection APIs?

What information is refreshed through subsystem selection APIs?

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

Copyright 1990-2002 Power Technologies, Inc.

GUIDE TO PSS/E BATCH COMMANDS

CHAPTER 1 - POWER FLOW APIS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-1

Default Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-1

GUIDE TO PSS/E BATCH COMMANDS

Power Technologies, Inc.

GUIDE TO PSS/E BATCH COMMANDS

Power Technologies, Inc.

1.82 MSLVAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-104

GUIDE TO PSS/E BATCH COMMANDS

Power Technologies, Inc.

1.127 RECNAPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-158

GUIDE TO PSS/E BATCH COMMANDS

Power Technologies, Inc.

1.172 TREEAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-217

CHAPTER 2 - LOAD FLOW DATA CHANGING APIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1

Area Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1

GUIDE TO PSS/E BATCH COMMANDS

Power Technologies, Inc.

CHAPTER 3 - OPTIMAL POWER FLOW APIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Data Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

GUIDE TO PSS/E BATCH COMMANDS

Power Technologies, Inc.

3.14.10 Adjustable Bus Shunt Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-41

CHAPTER 4 - DYNAMICS SIMULATION APIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-1

GUIDE TO PSS/E BATCH COMMANDS

Power Technologies, Inc.

CHAPTER 5 - SUBSYSTEM DEFINITION APIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

System Initialization Definition APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

CHAPTER 6 - SUBSYSTEM SELECTION APIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Area Subsystem Selection APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

GUIDE TO PSS/E BATCH COMMANDS

Power Technologies, Inc.

6.2.9 SBSVLMCBR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-8

GUIDE TO PSS/E BATCH COMMANDS

This page intentionally left blank.

GUIDE TO PSS/E BATCH COMMANDS

1.1 Default Information

GUIDE TO PSS/E BATCH COMMANDS

POWER FLOW APIS

Power Technologies, Inc.

Is the mismatch tolerance (input).

Is an array of seven elements specifying solution options (input). The

GUIDE TO PSS/E BATCH COMMANDS

POWER FLOW APIS

Power Technologies, Inc.

Is the name of Distribution Factor Data file (input).

Is the name of Contingency Solution Output file (input).

Is the error return (output).

Is the number of error entries in PBUF02 (output).

GUIDE TO PSS/E BATCH COMMANDS

POWER FLOW APIS

Power Technologies, Inc.

Is the "all" buses or selected subsystem flag (input).