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.

GUIDE TO PSS/E BATCH COMMANDS

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

GUIDE TO PSS/E BATCH COMMANDS

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

iii

TABLE OF CONTENTS

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

TABLE OF CONTENTS

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

vii

TABLE OF CONTENTS

4.31
4.32
4.33
4.34
4.35
4.36

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

ix

This page intentionally left blank.

GUIDE TO PSS/E BATCH COMMANDS

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

GUIDE TO PSS/E BATCH COMMANDS

1-1

POWER FLOW APIS

ACCCAPI

Power Technologies, Inc.

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) = 0, disable.
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) = 0, disable.
OPTIONS(3) = 1, enable.
OPTIONS(4), dc tap adjustment flag.
OPTIONS(4) = 0, disable.
OPTIONS(4) = 1, enable.
OPTIONS(5), switched shunt adjustment flag.
OPTIONS(5) = 0, disable.
OPTIONS(5) = 1, enable.
OPTIONS(6), solution method flag.
OPTIONS(6) = 0, FDNS.
OPTIONS(6) = 1, FNSL.
OPTIONS(7), non-divergent solution flag.
OPTIONS(7) = 0, disable.
OPTIONS(7) = 1, enable.

1-2

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

ACCCAPI

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

1-3

POWER FLOW APIS

ALPHNW

Power Technologies, Inc.

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 = 0, no error occurred.
IERR = 1, either ALL or SID is in error.

1-4

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

1-5

POWER FLOW APIS

ANSIAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, no case in memory.
IERR = 2, sequence data not in case.
IERR = 3, invalid OPTIONS value.
IERR = 4, invalid VALUES value.
IERR = 5, invalid INARG value.
IERR = 6, error opening file FILARG.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-6

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

AREA_INTERCHANGE_CONTROL_API

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-7

POWER FLOW APIS

AREANW

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.

1-8

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

ARNMNW

Power Technologies, Inc.

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

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 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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.
IERR = 3, IANEW is not between 1 and AREAS.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-9

POWER FLOW APIS

ASCCNW

Power Technologies, Inc.

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

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 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(2) = 0, ignore calculation.
STATUS(2) = 1, perform calculation.
STATUS(3), line-end fault calculation.
STATUS(3) = 0, ignore calculation.
STATUS(3) = 1, perform calculation.
STATUS(4), flat-condition fault calculation.
STATUS(4) = 0, ignore calculation.
STATUS(4) = 1, perform calculation.
STATUS(5), double-precision fault calculation.
STATUS(5) = 0, ignore calculation.
STATUS(5) = 1, perform 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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

ASCCNW

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.
IERR = 3, RFILE and/or FFILE is in error.
IERR = 4, no sequence data in the case.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-11

POWER FLOW APIS

BASE_FREQUENCY_API

Power Technologies, Inc.

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

Is the value of the option setting (input if IOCODE is 0 or BAT_ command,

output if IOCODE is 1).

Integer IOCODE

Indicates the operation mode of the API (input).

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid RVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-12

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

BGENNW

Power Technologies, Inc.

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

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 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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-13

POWER FLOW APIS

BKDYNW

Power Technologies, Inc.

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

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 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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

BMATAPI

Power Technologies, Inc.

1.12 BMATAPI
This API executes activity BMAT. This API uses the default element specification as described in
Section 1.1. The API is invoked by the use of the statement:
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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid OPTIONS value.
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

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-15

POWER FLOW APIS

BRCHNW

Power Technologies, Inc.

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

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 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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

BRCHNW

Power Technologies, Inc.

Integer IERR

PSS/E-29

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, one of the TOLVAL values is in error.

GUIDE TO PSS/E BATCH COMMANDS

1-17

POWER FLOW APIS

BSNMNW

Power Technologies, Inc.

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

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 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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

BSNMNW

Power Technologies, Inc.

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 = 1, output to the progress window.
OUT = 2, no output.

GUIDE TO PSS/E BATCH COMMANDS

1-19

POWER FLOW APIS

BSNMNW

Power Technologies, Inc.

Character OFILE*260 Is the bus translation output file.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
If OPT = 0:
IERR = 1, either ALL or SID is in error.
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 = 9, last OPT not 0.
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 = 9, last OPT not 0 or 4.
IERR = 7, STATUS is in error.
IERR = 15, BUSRNG(1) = 0.
IERR = 5, bus range error.
If OPT = 5:
IERR = 9, last OPT not 0.
IERR = 10, invalid starting bus number.
IERR = 11, not enough numbers between BUSRNG(1) and 99997.
If OPT = 15:
IERR = 9, last OPT not 0 or 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 = 9, last OPT not 15.
IERR = 14, not enough OPT 15 calls.
If OPT = 35:
IERR = 9, last OPT not 15.

1-20

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

BUS_INPUT_API

Power Technologies, Inc.

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
API is invoked by the use of the statement:
CALL BUS_INPUT_API(IVAL, IOCODE, IERR, NERR)

or
BAT_BUS_INPUT

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, bus numbers.
IVAL = 1, extended bus names.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-21

POWER FLOW APIS

BUS_OUTPUT_API

Power Technologies, Inc.

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

Is the value of the option setting (input if IOCODE is 0 or BAT_ command,

output if IOCODE is 1).
IVAL = 0, bus numbers.
IVAL = 1, extended bus names.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-22

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

BUSNAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, BUSLO < 1.
IERR = 2, BUSHI < BUSLO.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-23

POWER FLOW APIS

CASENW

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, error opening SFILE.
IERR = 2, error reading from SFILE.

1-24

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

CMPRNW

Power Technologies, Inc.

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

Is a valid subsystem ID. Valid subsystem IDs range from 0 to 3. A subsystem

must have been previously defined (input).

Integer APIOPT

Is the mode of operation in the API.

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).

GUIDE TO PSS/E BATCH COMMANDS

1-25

POWER FLOW APIS

CMPRNW

Power Technologies, Inc.

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

1-26

Is the error return.

IERR = 0, no error occurred.
IERR = 1, SID is in error.
IERR = 2, APIOPT is in error.
IERR = 3, STATUS is in error.
IERR = 4, error opening CFILE.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

CNTBNW

Power Technologies, Inc.

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
the use of the statement:
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

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 buses subsystem flag (input).

ALL = 1, process all buses.
ALL = 0, process only selected buses.

Integer APIOPT

Is the mode of operation in the API.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-27

POWER FLOW APIS

CNTBNW

Integer NEXT

Power Technologies, Inc.

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.
BUS(1) returned as controlled bus whose voltage schedule may be
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)

Is an array of three elements. They are used to control reporting options.

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

Real V(2)

Is an array of two elements.

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

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 2, STATUS is in error.
IERR = 3, V(1) <= 0.5 or V(1) >= 1.5.
IERR = 5, unexpected APIOPT value.

1-28

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

CNTBNW

Power Technologies, Inc.

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.
BUS(1) returned as controlled bus whose voltage schedule may be
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.

When APIOPT = 3, specify voltage band for load drop compensating transformer.
Integer STATUS(3)

Is an array of three elements. They are used to control reporting options.

STATUS(1) = 0, no change.
STATUS(1) = 1, new voltage band in V(1) and V(2).
STATUS(2), not used except for ECHO.
STATUS(3), not used except for ECHO.

Real V(2)

Is an array of two elements.

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

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 2, STATUS is in error.
IERR = 3, V(1) >= V(2).
IERR = 5, unexpected APIOPT value.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-29

POWER FLOW APIS

CNTBNW

Integer NEXT

Power Technologies, Inc.

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 voltage band, VMIN, VMAX of load drop compensating transformer.
BUS(1) returned as controlled bus whose voltage band may be 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.

1-30

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

CONNECTIVITY_CHECK_API

Power Technologies, Inc.

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

Is the value of the option setting (input if IOCODE is 0 or BAT_ command,

output if IOCODE is 1).
IVAL = 0, no solution connectivity check before power flow solutions.
IVAL = 1, perform solution connectivity check before power flow
solutions.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-31

POWER FLOW APIS

CONGAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error.
IERR = 1, invalid value of OPT.
IERR = 2, generators are already converted.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-32

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

CONLNW

Power Technologies, Inc.

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

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 APIOPT

Is the mode of operation in the API.

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

GUIDE TO PSS/E BATCH COMMANDS

1-33

POWER FLOW APIS

CONLNW

Integer IERR

1-34

Power Technologies, Inc.

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, APIOPT is in error.
IERR = 3, STATUS is in error.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

DC_TAP_ADJUSTMENT_API

Power Technologies, Inc.

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

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.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-35

POWER FLOW APIS

DCCCAPI

Power Technologies, Inc.

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(5) = 1, yes.
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.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

DCCCAPI

Power Technologies, Inc.

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

Is the error return (output).

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

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-37

POWER FLOW APIS

DCLFNW

Power Technologies, Inc.

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

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 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.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

Integer IERR

PSS/E-29

POWER FLOW APIS

DCLFNW

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.
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.

GUIDE TO PSS/E BATCH COMMANDS

1-39

POWER FLOW APIS

DFAXAPI

Power Technologies, Inc.

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).
Character DFXFILE*260 Is the name of Distribution Factor Data input file (input).
Integer IERR

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, no case in memory.
IERR = 2, invalid OPTIONS value.
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.
IERR = 12, working case has island without a swing bus.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-40

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

DFTIAPI

Power Technologies, Inc.

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
the use of the statement:
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

values are as follows:
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

GUIDE TO PSS/E BATCH COMMANDS

1-41

POWER FLOW APIS

DFTIAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
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 = 5, APIOPT is in error.
IERR = 6, error opening Saved Case File CFILE.

Integer NERR

Number of error entries in PBUF02 (output).

1-42

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

DIFFNW

Power Technologies, Inc.

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

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 APIOPT

Is the mode of operation in the API.

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) = 0, original 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

GUIDE TO PSS/E BATCH COMMANDS

1-43

POWER FLOW APIS

DIFFNW

Power Technologies, Inc.

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) = 0, original 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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
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 = 5, APIOPT is in error.
IERR = 6, error initializing the comparison case.

GUIDE TO PSS/E BATCH COMMANDS

1-45

POWER FLOW APIS

DSCNAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, bus BUS not in working case.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-46

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

DYN_UNBAL_FAULT

Power Technologies, Inc.

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.

GUIDE TO PSS/E BATCH COMMANDS

1-47

POWER FLOW APIS

DYN_UNBAL_FAULT

Power Technologies, Inc.

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.
Character DFXFILE*260 Is the name of Distribution Factor Data input file (input).
Integer IERR

Is the error return (output).

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

Is the number of error entries in PBUF02 (output).

1-48

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

ECDINW

Power Technologies, Inc.

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
use of the statement:
ECDINW(SID, ALL, APIOPT, GFILE, PROFILE, DESPWR, CAPCTY, IERR)

or:
BAT_ECDI

SID

ALL

APIOPT

GFILE

PROFILE

DESPWR

CAPCTY

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 APIOPT

Is the mode of operation in the API.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, APIOPT is in error.
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

GUIDE TO PSS/E BATCH COMMANDS

1-49

POWER FLOW APIS

ECHOAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, error opening file IDVFILE.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-50

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

EEQVNW

Power Technologies, Inc.

1.34 EEQVNW
This API is used to construct an electrical equivalent of a subsystem of the network contained in the
working case. The API is invoked by the use of the statement:
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

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

ALL = 1, process all buses.
ALL = 0, process only selected buses.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-51

POWER FLOW APIS

EQRDNW

Power Technologies, Inc.

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)

SID ALL STATUS(1) STATUS(2)

STATUS(6) STATUS(7) STATUS(8)

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

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

ALL = 1, process all buses.
ALL = 0, process only selected buses.

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
enabled. They are as follows.
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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.

1-52

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

EXAMNW

Power Technologies, Inc.

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
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 = 0, no error occurred.
IERR = 1, either ALL or SID is in error.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-53

POWER FLOW APIS

EXTRNW

Power Technologies, Inc.

1.37 EXTRNW
This API is used to purge specified buses and all branches connected to them from the working case.
The API is invoked by the use of the statement:
EXTRNW(SID, ALL, STATUS, IERR)

or:
BAT_EXTR

SID

ALL

STATUS(1)

STATUS(2)

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

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

ALL = 1, process all buses.
ALL = 0, process only selected buses.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.

1-54

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

FACTAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, no case in memory.
IERR = 2, generators are not "converted".

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-55

POWER FLOW APIS

FDNSAPI

Power Technologies, Inc.

1.39 FDNSAPI
This API executes activity FDNS. This API uses the default element specification as described in
Section 1.1. The API is invoked by the use of the statement:
FDNSAPI(OPTIONS, IERR, NERR)

or
BAT_FDNS
OPTIONS(5)

OPTIONS(1) OPTIONS(2) OPTIONS(3)

OPTIONS(6) OPTIONS(7) OPTIONS(8)

OPTIONS(4)

where:
Integer OPTIONS(8)

Is an array of eight 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) = 0, disable.
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) = 0, disable.
OPTIONS(3) = 1, enable.
OPTIONS(4), dc tap adjustment flag.
OPTIONS(4) = 0, disable.
OPTIONS(4) = 1, enable.
OPTIONS(5), switched shunt adjustment flag.
OPTIONS(5) = 0, disable.
OPTIONS(5) = 1, enable.
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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

FDNSAPI

Power Technologies, Inc.

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

gets small).
OPTIONS(7) = -1, ignore var limits.
OPTIONS(8), non-divergent solution flag.
OPTIONS(8) = 0, disable.
OPTIONS(8) = 1, enable.
Integer IERR

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid OPTIONS value.
IERR = 2, generators are "converted".
IERR = 3, working case has island without a swing bus.

Integer NERR

Is the number of error entries in PBUF02 (output).

OPTIONS(6), flat start flag.
OPTIONS(6) = 0, do not flat start.
OPTIONS(6) = 1, flat start.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-57

POWER FLOW APIS

FILE_OVERWRITE_API

Power Technologies, Inc.

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,

output if IOCODE is 1).
IVAL = 0, ask first.
IVAL = 1, overwrite.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-58

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

FINDAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, no case in memory.
IERR = 2, error decoding BSKV.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-59

POWER FLOW APIS

FLATAPI

Power Technologies, Inc.

1.42 FLATAPI
This API executes activity FLAT. This API uses the default element specification as described in
Section 1.1. The API is invoked by the use of the statement:
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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid OPTIONS value.
IERR = 2, invalid VALUES value.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-60

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

FNSLAPI

Power Technologies, Inc.

1.43 FNSLAPI
This API executes activity FNSL. This API uses the default element specification as described in
Section 1.1. The API is invoked by the use of the statement:
FNSLAPI(OPTIONS, IERR, NERR)

or
BAT_FNSL
OPTIONS(5)

OPTIONS(1) OPTIONS(2) OPTIONS(3)

OPTIONS(6) OPTIONS(7) OPTIONS(8)

OPTIONS(4)

where:
Integer OPTIONS(8)

Is an array of eight 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) = 0, disable.
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) = 0, disable.
OPTIONS(3) = 1, enable.
OPTIONS(4), dc tap adjustment flag.
OPTIONS(4) = 0, disable.
OPTIONS(4) = 1, enable.
OPTIONS(5), switched shunt adjustment flag.
OPTIONS(5) = 0, disable.
OPTIONS(5) = 1, enable.
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.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-61

POWER FLOW APIS

FNSLAPI

Power Technologies, Inc.

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

gets small).
OPTIONS(7) = -1, ignore var limits.
OPTIONS(8), non-divergent solution flag.
OPTIONS(8) = 0, disable.
OPTIONS(8) = 1, enable.
Integer IERR

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid OPTIONS value.
IERR = 2, generators are "converted".
IERR = 3, working case has island without a swing bus.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-62

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

GCAPNW

Power Technologies, Inc.

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

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 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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, OPT is in error.
IERR = 3, GFILE is in error.

GUIDE TO PSS/E BATCH COMMANDS

1-63

POWER FLOW APIS

GDIFAPI

Power Technologies, Inc.

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.

The API is invoked by the use of the statement:

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
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

Is the number of error entries in PBUF02 (output).

1-64

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

GENSNW

Power Technologies, Inc.

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

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 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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, OPT or VREV is in error.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-65

POWER FLOW APIS

GEOLNW

Power Technologies, Inc.

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

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 OPT

Is used to restrict the type of machine to tabulate.

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

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, OPT is in error.

1-66

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

GNETNW

Power Technologies, Inc.

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

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 = 0, no error occurred.
IERR = 1, either ALL or SID is in error.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-67

POWER FLOW APIS

GSDFLT

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

IMPCAPI

Power Technologies, Inc.

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 DFXFILE*260 Is the name of Distribution Factor Data input file (input).
Character ATCFILE*260 Is the name of ATC update input file; blank for none (input).
Integer IERR

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, no case in memory.
IERR = 2, invalid EVENT value.
IERR = 3, no transactions defined.
IERR = 4, no DFAX input file specified.
IERR = 5, subroutine INPROC error.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-69

POWER FLOW APIS

INLFAPI

Power Technologies, Inc.

1.51 INLFAPI
This API executes activity INLF. This API uses the default element specification as described in
Section 1.1. The API is invoked by the use of the statement:
INLFAPI(OPTIONS, FILE, IERR, NERR)

or
BAT_INLF
OPTIONS(5)

OPTIONS(1) OPTIONS(2) OPTIONS(3)

OPTIONS(6) OPTIONS(7) FILE

OPTIONS(4)

where:
Integer OPTIONS(7)

Is an array of seven elements specifying solution options (input). The

values are as follows:
OPTIONS(1), solution type.
OPTIONS(1) = 0, inertial.
OPTIONS(1) = 1, governor response.
OPTIONS(2), tap adjustment flag.
OPTIONS(2) = 0, disable.
OPTIONS(2) = 1, enable stepping adjustment.
OPTIONS(2) = 2, enable direct adjustment.
OPTIONS(2) = -1, solution type default (inertial => disabled; governor =>
stepping).
OPTIONS(3), phase shift adjustment flag.
OPTIONS(3) = 0, disable.
OPTIONS(3) = 1, enable.
OPTIONS(3) = -1, solution type default (inertial => disabled; governor =>
enabled).
OPTIONS(4), dc tap adjustment flag.
OPTIONS(4) = 0, disable.
OPTIONS(4) = 1, enable.
OPTIONS(4) = -1, solution type default (inertial => disabled; governor =>
enabled).
OPTIONS(5), switched shunt adjustment flag.
OPTIONS(5) = 0, disable.
OPTIONS(5) = 1, enable.
OPTIONS(5) = -1, solution type default (inertial => enabled; governor =>
enabled).
OPTIONS(6), var limit flag.
OPTIONS(6) = 0, apply var limits immediately.

1-70

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

INLFAPI

Power Technologies, Inc.

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

gets small).
OPTIONS(6) = -1, ignore var limits.
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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid OPTIONS value.
IERR = 2, error opening input file FILE.
IERR = 3, generators are "converted".

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-71

POWER FLOW APIS

INTANW

Power Technologies, Inc.

1.52 INTANW
This API is used to summarize tie flows between an interchange area and all other areas in the
working case. The API is invoked by the use of the statement:
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).

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

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.

1-72

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

INTZNW

Power Technologies, Inc.

1.53 INTZNW
This API is used to summarize tie flows between each zone and all other zones in the working case.
The API is invoked by the use of the statement:
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
subsystem must have been previously defined (input).

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-73

POWER FLOW APIS

JOINAPI/JOINNW

Power Technologies, Inc.

1.54 JOINAPI/JOINNW
The API is invoked by the use of the statement:
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.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

JOINAPI/JOINNW

Power Technologies, Inc.

Integer IERR

Is the error return (output).

IERR = 0, no error occurred.
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

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-75

POWER FLOW APIS

LAMPNW

Power Technologies, Inc.

1.55 LAMPNW
This API is used to print power flow and amp data in a wide format, greater than 80 columns. The
API is invoked by the use of the statement:
LAMPNW(SID, ALL, IERR)

or:
BAT_LAMP

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 (input).

Integer ALL

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

ALL = 1, process all buses.
ALL = 0, process only selected buses.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.

1-76

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

LINE_SHUNT_REPORTING_API

Power Technologies, Inc.

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".
The API is invoked by the use of the statement:
LINE_SHUNT_REPORTING_API(IVAL, IOCODE, IERR, NERR)

or
BAT_LINE_SHUNT_REPORTING

IVAL

where:
Integer IVAL

Is the value of the option setting (input it IOCODE is 0 or BAT_command,

output if IOCODE is 1).
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

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-77

POWER FLOW APIS

LINES_PER_PAGE_API

Power Technologies, Inc.

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
API is invoked by the use of the statement:
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

Indicates the operation mode of the API (input).

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, negative IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Number of error entries in PBUF02 (output).

1-78

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

LISTNW

Power Technologies, Inc.

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

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 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
= 24, three-winding transformer
control data

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, OPT or VREV is in error.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-79

POWER FLOW APIS

LLRFAPI

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

LLRFAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, no case in memory.
IERR = 2, invalid APIOPT value.
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 = 5, no DFAX input file specified.
IERR = 6, no transactions defined.
IERR = 7, subroutine INPROC error.
IERR = 8, invalid RVAL value.
IERR = 9, invalid OPTIONS value.

Integer NERR

Number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-81

POWER FLOW APIS

LOUTNW

Power Technologies, Inc.

1.60 LOUTNW
This API is used to print power flow data in a wide format, greater than 80 columns. The API is
invoked by the use of the statement:
LOUTNW(SID, ALL, IERR)

or:
BAT_LOUT

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 (input).

Integer ALL

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

ALL = 1, process all buses.
ALL = 0, process only selected buses.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.

1-82

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

LTAPAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
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

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-83

POWER FLOW APIS

MATRIX_GROWTH_FACTOR_API

Power Technologies, Inc.

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
the use of the statement:
CALL MATRIX_GROWTH_FACTOR_API(RVAL, IOCODE, IERR, NERR)

or
BAT_MATRIX_GROWTH_FACTOR

RVAL

where:
Integer RVAL

Is the value of the option setting (input if IOCODE is 0 or BAT_ command,

output if IOCODE is 1).

Integer IOCODE

Indicates the operation mode of the API (input).

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid RVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-84

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

MBID2DC

Power Technologies, Inc.

1.63 MBID2DC
This API changes the dc line number of the specified two-terminal dc line. The API is invoked by
the use of the statement:
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

Is the error return (output).

IERR = 0, no error occurred.
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

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-85

POWER FLOW APIS

MBID3WND

Power Technologies, Inc.

1.64 MBID3WND
This API changes the identifier of the specified three-winding transformer. The API is invoked by
the use of the statement:
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

Is the error return (output).

IERR = 0, no error occurred.
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

Is the number of error entries in PBUF02 (output).

1-86

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

MBIDATRN

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
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

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-87

POWER FLOW APIS

MBIDBRN

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, FRMBUS or TOBUS not in working case.
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.
IERR = 4, IDNEW is invalid identifier.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-88

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

MBIDFACTS

Power Technologies, Inc.

1.67 MBIDFACTS
This API changes the FACTS device number of the specified FACTS device. The API is invoked
by the use of the statement:
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

Is the error return (output).

IERR = 0, no error occurred.
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

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-89

POWER FLOW APIS

MBIDLOAD

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
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

Is the number of error entries in PBUF02 (output).

1-90

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

MBIDMAC

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, FRMBUS not in working case.
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

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-91

POWER FLOW APIS

MBIDMDC

Power Technologies, Inc.

1.70 MBIDMDC
This API changes the dc line number of the specified multi-terminal dc line. The API is invoked by
the use of the statement:
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

Is the error return (output).

IERR = 0, no error occurred.
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, multi-terminal dc line table full.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-92

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

MBIDMSL

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, FRMBUS or TOBUS not in working case.
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.
IERR = 4, IDNEW is invalid identifier.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-93

POWER FLOW APIS

MBIDVSC

Power Technologies, Inc.

1.72 MBIDVSC
This API changes the VSC dc line name of the specified VSC dc line. The API is invoked by the
use of the statement:
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

Is the error return (output).

IERR = 0, no error occurred.
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

Is the number of error entries in PBUF02 (output).

1-94

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

MCREAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid STATUS value.
IERR = 2, error opening input file FILE.
IERR = 3, generators are converted.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-95

POWER FLOW APIS

MODRNW

Power Technologies, Inc.

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

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

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

ALL = 1, process all buses.
ALL = 0, process only selected buses.

Integer APIOPT

Is the mode of operation in the API.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, APIOPT is in error.
IERR = 3, IRAT, RLOAD, or FMAX is in error.

1-96

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

MOVE3WND

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
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

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-97

POWER FLOW APIS

MOVEBRN

Power Technologies, Inc.

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
API is invoked by the use of the statement:
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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, FRMBUS, TOBUS or NEWTOBUS not in working case.
IERR = 2, circuit CKT connecting FRMBUS and TOBUS not in working
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

Is the number of error entries in PBUF02 (output).

1-98

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

MOVELOAD

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, FRMBUS or NEWBUS not in working case.
IERR = 2, load ID at bus FRMBUS 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

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-99

POWER FLOW APIS

MOVELOADS

Power Technologies, Inc.

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
invoked by the use of the statement:
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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, FRMBUS or TOBUS not in working case.
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

Is the number of error entries in PBUF02 (output).

1-100

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

MOVEMAC

Power Technologies, Inc.

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

Is the bus to which machine "ID" is connected (input).

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, FRMBUS or NEWBUS not in working case.
IERR = 2, machine ID at bus FRMBUS 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

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-101

POWER FLOW APIS

MOVEPLNT

Power Technologies, Inc.

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
API is invoked by the use of the statement:
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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, FRMBUS or TOBUS not in working case.
IERR = 2, no plant present on bus FRMBUS.
IERR = 3, FRMBUS and TOBUS are the same bus.
IERR = 4, TOBUS already has plant data (move individual machines).

Integer NERR

Is the number of error entries in PBUF02 (output).

1-102

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

MOVESWS

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, FRMBUS or TOBUS not in working case.
IERR = 2, no switched shunt present on bus FRMBUS.
IERR = 3, FRMBUS and TOBUS are the same bus.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-103

POWER FLOW APIS

MSLVAPI

Power Technologies, Inc.

1.82 MSLVAPI
This API executes activity MSLV. This API uses the default element specification as described in
Section 1.1. The API is invoked by the use of the statement:
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:
OPTIONS(1), tap adjustment flag.
OPTIONS(1) = 0, disable.
OPTIONS(1) = 1, enable.
OPTIONS(2), area interchange adjustment flag.
OPTIONS(2) = 0, disable.
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), flat start flag.
OPTIONS(3) = 0, do not flat start.
OPTIONS(3) = 1, flat start.
OPTIONS(4), dc tap adjustment flag.
OPTIONS(4) = 0, disable.
OPTIONS(4) = 1, enable.
OPTIONS(5), switched shunt adjustment flag.
OPTIONS(5) = 0, disable.
OPTIONS(5) = 1, enable.
OPTIONS(6), var limit flag.
OPTIONS(6) = 0, apply var limits.
OPTIONS(6) = 1, ignore var limits.

1-104

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

MSLVAPI

Power Technologies, Inc.

Integer IERR

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid OPTIONS value.
IERR = 2, generators are "converted".
IERR = 3, working case has island without a swing bus.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-105

POWER FLOW APIS

MTDCAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, no unblocked multi-terminal dc lines in case.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-106

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

MULTISECTION_LINE_REPORTING_API

Power Technologies, Inc.

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

Is the value of the option setting (input it IOCODE is 0 or BAT_command,

output if IOCODE is 1).
IVAL = 0, off.
IVAL = 1, on.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-107

POWER FLOW APIS

NETGNW

Power Technologies, Inc.

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

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 = 0, no error occurred.
IERR = 1, either ALL or SID is in error.

1-108

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

NEWCASNW

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, base kV is in error.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-109

POWER FLOW APIS

NEWTON_TOLERANCE_API

Power Technologies, Inc.

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

Is the value of the option setting (input if IOCODE is 0 or BAT_ command,

output if IOCODE is 1).

Integer IOCODE

Indicates the operation mode of the API (input).

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid RVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-110

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

NON_DIVERGENT_API

Power Technologies, Inc.

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

Is the value of the option setting (input it IOCODE is 0 or BAT_command,

output if IOCODE is 1).
IVAL = 0, disable non-divergent Newton solution option.
IVAL = 1, enable non-divergent Newton solution option.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-111

POWER FLOW APIS

NRDFLT

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

NRDFLT

Power Technologies, Inc.

Integer IERR

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid METHOD value.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-113

POWER FLOW APIS

NSOLAPI

Power Technologies, Inc.

1.90 NSOLAPI
This API executes activity NSOL. This API uses the default element specification as described in
Section 1.1. The API is invoked by the use of the statement:
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)

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) = 0, disable.
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) = 0, disable.
OPTIONS(3) = 1, enable.
OPTIONS(4), dc tap adjustment flag.
OPTIONS(4) = 0, disable.
OPTIONS(4) = 1, enable.
OPTIONS(5), switched shunt adjustment flag.
OPTIONS(5) = 0, disable.
OPTIONS(5) = 1, enable.
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-114

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

NSOLAPI

Power Technologies, Inc.

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

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid OPTIONS value.
IERR = 2, generators are "converted".
IERR = 3, working case has island without a swing bus.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-115

POWER FLOW APIS

ORDRAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid OPT.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-116

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

OTDFAPI

Power Technologies, Inc.

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:
Character DFXFILE*260 Is the name of Distribution Factor Data input file (input).
Integer IERR

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, no case in memory.
IERR = 2, subroutine GETLOS error (generators are "converted" or
swingless island present).
IERR = 3, no DFAX input file specified.
IERR = 4, subroutine INPROC error.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-117

POWER FLOW APIS

OUTSNW

Power Technologies, Inc.

1.93 OUTSNW
This API is used to tabulate those components in the working case that are removed from service.
The API is invoked by the use of the statement:
OUTSNW(SID, ALL, IERR)

or:
BAT_OUTS

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 (input).

Integer ALL

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

ALL = 1, process all buses.
ALL = 0, process only selected buses.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.

1-118

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

OWNMAPI

Power Technologies, Inc.

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

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 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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.
IERR = 3, IONEW is not between 1 and OWNERS.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-119

POWER FLOW APIS

OWNRNW

Power Technologies, Inc.

1.95 OWNRNW
This API is used to provide a tabulation by owner interchange of the desired owner net interchange.
The API is invoked by the use of the statement:
OWNRNW(SID, ALL, IERR)

or:
BAT_OWNR

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" owners or selected subsystem flag (input).

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

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.

1-120

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

PP_ACCC

Power Technologies, Inc.

1.96 PP_ACCC
This API is used to invoke the AC Contingency Calculation report process. The API is invoked by
the use of the statement:
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

GUIDE TO PSS/E BATCH COMMANDS

1-121

POWER FLOW APIS

PP_ACCC

Integer INTVAL(5)

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, Error in STATUS.
IERR = 2, Error in INTVAL.
IERR = 3, Error in REALVAL.
IERR = 4, Error in RFILE.

1-122

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

PATHAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, error setting path PATHNAME.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-123

POWER FLOW APIS

PHASE_SHIFT_ADJUSTMENT_API

Power Technologies, Inc.

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

Is the value of the option setting (input it IOCODE is 0 or BAT_command,

output if IOCODE is 1).
IVAL = 0, disabled.
IVAL = 1, enabled.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-124

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

POLYAPI

Power Technologies, Inc.

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
(input). The values are as follows:
OPTIONS(1), base case rating set.
OPTIONS(1) = 1, RATEA.
OPTIONS(1) = 2, RATEB.
OPTIONS(1) = 3, RATEC.
OPTIONS(2), contingency case rating set.
OPTIONS(2) = 1, RATEA.
OPTIONS(2) = 2, RATEB.
OPTIONS(2) = 3, RATEC.
OPTIONS(3), base case line flow code.
OPTIONS(3) = 0, dc base case.
OPTIONS(3) = 1, ac base case.
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(5) = 1, include.
OPTIONS(6), list study system buses.
OPTIONS(6) = 0, no.
OPTIONS(6) = 1, yes.
OPTIONS(7), list opposing system buses.
OPTIONS(7) = 0, no.
OPTIONS(7) = 1, yes.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-125

POWER FLOW APIS

POLYAPI

Power Technologies, Inc.

OPTIONS(8), list study system tie lines.

OPTIONS(8) = 0, no.
OPTIONS(8) = 1, yes.
OPTIONS(9), add study system tie lines to monitored line list.
OPTIONS(9) = 0, no.
OPTIONS(9) = 1, yes.
OPTIONS(10), output format code.
OPTIONS(10) = 0, summary output.
OPTIONS(10) = 1, full output.
OPTIONS(11), convert MVA ratings to estimated MW ratings.
OPTIONS(11) = 0, no.
OPTIONS(11) = 1, yes.
OPTIONS(12), abort if MW mismatch exceeds TOLS(1).
OPTIONS(12) = 0, abort.
OPTIONS(12) = 1, continue.
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(1), required MW mismatch tolerance for continuing.
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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

POLYAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error.
IERR = 1, no case in memory.
IERR = 2, invalid OPTIONS value.
IERR = 3, invalid TOLS value.
IERR = 4, no DFAX input file specified.
IERR = 5, subroutine GETLOS error (generators are "converted" or
swingless island present).
IERR = 6, subroutine INPROC error.
IERR = 7, same subsystem label specified for study and opposing
subsystems.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-127

POWER FLOW APIS

POUTNW

Power Technologies, Inc.

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

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

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

ALL = 1, process all buses.
ALL = 0, process only selected buses.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.

1-128

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

POWER_OUTPUT_API

Power Technologies, Inc.

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
API is invoked by the use of the statement:
POWER_OUTPUT_API(IVAL, IOCODE, IERR, NERR)

or
BAT_POWER_OUTPUT

IVAL

where:
Integer IVAL

Is the value of the option setting (input it IOCODE is 0 or BAT_command,

output if IOCODE is 1).
IVAL = 0, KVA.
IVAL = 1, MVA.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-129

POWER FLOW APIS

PRTIAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, no case in memory.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-130

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

PURG2DC

Power Technologies, Inc.

1.103 PURG2DC
This API deletes the specified two-terminal dc line from the working case. The API is invoked by
the use of the statement:
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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid dc line number.
IERR = 2, dc line DC not in working case.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-131

POWER FLOW APIS

PURG3WND

Power Technologies, Inc.

1.104 PURG3WND
This API deletes the specified three-winding transformer from the working case. The API is
invoked by the use of the statement:
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

Is the error return (output).

IERR = 0, no error occurred.
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

Is the number of error entries in PBUF02 (output).

1-132

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

PURGATRN

Power Technologies, Inc.

1.105 PURGATRN
This API deletes the specified inter-area transfer from the working case. The API is invoked by the
use of the statement:
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

Is the error return (output).

IERR = 0, no error occurred.
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

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-133

POWER FLOW APIS

PURGBRN

Power Technologies, Inc.

1.106 PURGBRN
This API deletes the specified non-transformer branch or two-winding transformer from the
working case. The API is invoked by the use of the statement:
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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, FRMBUS or TOBUS not in working case.
IERR = 2, circuit CKT connecting FRMBUS and TOBUS not in working
case.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-134

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

PURGFACTS

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid FACTS device number.
IERR = 2, FACTS device DEVICE not in working case.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-135

POWER FLOW APIS

PURGLOAD

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, FRMBUS not in working case.
IERR = 2, load ID at bus FRMBUS not in working case.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-136

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

PURGLOADS

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, FRMBUS not in working case.
IERR = 2, no loads at bus FRMBUS.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-137

POWER FLOW APIS

PURGMAC

Power Technologies, Inc.

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

Is the bus to which machine "ID" is connected (input).

Character ID*2

Is the machine identifier of the machine to be removed (input).

Integer IERR

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, FRMBUS not in working case.
IERR = 2, machine ID at bus FRMBUS not in working case.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-138

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

PURGMDC

Power Technologies, Inc.

1.111 PURGMDC
This API deletes the specified multi-terminal dc line from the working case. The API is invoked by
the use of the statement:
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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid dc line number.
IERR = 2, dc line DC not in working case.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-139

POWER FLOW APIS

PURGMSL

Power Technologies, Inc.

1.112 PURGMSL
This API deletes the specified multi-section line grouping from the working case. The API is
invoked by the use of the statement:
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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, FRMBUS or TOBUS not in working case.
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

Is the number of error entries in PBUF02 (output).

1-140

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

PURGMUT

Power Technologies, Inc.

1.113 PURGMUT
This API deletes the specified zero sequence mutual coupling from the working case. The API is
invoked by the use of the statement:
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

Is the error return (output).

IERR = 0, no error occurred.
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

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-141

POWER FLOW APIS

PURGNW

Power Technologies, Inc.

1.114 PURGNW
This API is used to delete designated outaged equipment items from the working case. The API is
invoked by the use of the statement:
PURGNW(SID, ALL, OPT, STATUS, IERR)

or:
BAT_PURG

SID

ALL

OPT

STATUS

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

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

ALL = 1, process all buses.
ALL = 0, process only selected buses.

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

Is the error return.

IERR = 0, no error.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS and/or OPT is in error.

1-142

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

PURGPLNT

Power Technologies, Inc.

1.115 PURGPLNT
This API deletes the plant and machine data at the specified bus from the working case. The API is
invoked by the use of the statement:
PURGPLNT (FRMBUS, IERR,NERR)

or
BAT_PURGPLNT

FRMBUS

where:
Integer FRMBUS

Is the bus whose plant is to be removed (input).

Integer IERR

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, FRMBUS not in working case.
IERR = 2, no plant at bus FRMBUS.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-143

POWER FLOW APIS

PURGSWS

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, FRMBUS not in working case.
IERR = 2, no switched shunt on bus FRMBUS.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-144

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

PURGVSC

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, VSC dc line NAME not in working case.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-145

POWER FLOW APIS

RANKNW

Power Technologies, Inc.

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

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 buses subsystem flag (input).

ALL = 1, process all buses.
ALL = 0, process only selected buses.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

RANKNW

Power Technologies, Inc.

Integer IERR

PSS/E-29

Is the error return.

IERR = 0, no error.
IERR = 1, either ALL or SID is in error.
IERR = 2, SSFILE and/or MNFILE is in error.
IERR = 3, IVAL or RVAL error.
IERR = 4, OFILE error.

GUIDE TO PSS/E BATCH COMMANDS

1-147

POWER FLOW APIS

RATENW

Power Technologies, Inc.

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

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

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

ALL = 1, process all buses.
ALL = 0, process only selected buses.

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

Is the error return.

IERR = 0, no error.
IERR = 1, either ALL or SID is in error.
IERR = 2, either IACT, ITL, or FMAX is in error.

1-148

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

RATING_SET_API

Power Technologies, Inc.

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

Is the value of the option setting (input it IOCODE is 0 or BAT_command,

output if IOCODE is 1).
IVAL = 1, RATEA.
IVAL = 2, RATEB.
IVAL = 3, RATEC.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-149

POWER FLOW APIS

RAWDAPI

Power Technologies, Inc.

1.121 RAWDAPI
This API outputs the working case in the form of a Power Flow Raw Data file (activity RAWD).
The API is invoked by the use of the statement:
RAWDAPI(SID, ALL, STATUS, OUT, OFILE, IERR, NERR)

or:
BAT_RAWD
STATUS(5)

SID ALL STATUS(1) STATUS(2)

STATUS(6) OUT OFILE

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

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

ALL = 0, process subsystem SID.
ALL = 1, process all buses.

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).

OUT = 0, output to a data file specified by OFILE.
OUT = 1, output to the progress window.

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

1-150

Is the error return.

IERR = 0, no error.
IERR = 1, no case in memory.
IERR = 2, SID or ALL is in error (invalid value or subsystem SID not
defined).
IERR = 3, STATUS value is in error.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

RAWDAPI

Power Technologies, Inc.

IERR = 4, OUT value is in error.

IERR = 5, error opening file OFILE.
Integer NERR

PSS/E-29

Is the number of error entries in PBUF02 (output).

GUIDE TO PSS/E BATCH COMMANDS

1-151

POWER FLOW APIS

RAWDNW

Power Technologies, Inc.

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
is invoked by the use of the statement:
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

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

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

ALL = 1, process all buses.
ALL = 0, process only selected buses.

Integer STATUS(5)

Is an array of five 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(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

Is the output option selection.

OUT = 0, output to a data file specified by OFILE.
OUT = 1, output to the progress window.

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

Integer IERR

1-152

Is the error return.

IERR = 0, no error.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.
IERR = 3, error opening OFILE.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

RDCHAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid NUMNAM.
IERR = 2, error opening input file FILE.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-153

POWER FLOW APIS

RDEQNW

Power Technologies, Inc.

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)

SID ALL STATUS(1) STATUS(2)

STATUS(6) STATUS(7) STATUS(8)

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

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

ALL = 1, process all buses.
ALL = 0, process only selected buses.

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
enabled. They are as follows.
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

Is the error return.

IERR = 0, no error.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.

1-154

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

READAPI

Power Technologies, Inc.

1.125 READAPI
This API executes activity READ, with all data in the input file being added to the working case.
The API is invoked by the use of the statement:
READAPI(NUMNAM, FILE, IERR, NERR)

or
BAT_READ

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 Power Flow Raw Data Input file (input).

Integer IERR

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid NUMNAM.
IERR = 2, error opening input file FILE.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-155

POWER FLOW APIS

READSUB

Power Technologies, Inc.

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

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 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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

READSUB

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid NUMNAM.
IERR = 2, error opening input file FILE.
IERR = 3, invalid STATUS value.
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

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-157

POWER FLOW APIS

RECNAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, bus BUS not in working case.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-158

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

REGBNW

Power Technologies, Inc.

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

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

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

ALL = 1, process all buses.
ALL = 0, process only selected buses.

Integer IERR

Is the error return.

IERR = 0, no error.
IERR = 1, either ALL or SID is in error.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-159

POWER FLOW APIS

REMMAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid OPT.
IERR = 2, invalid change mode.
IERR = 3, error opening input file FILE.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-160

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

RESQAPI

Power Technologies, Inc.

1.130 RESQAPI
This API executes activity RESQ, with all data in the input file being added to the working case.
The API is invoked by the use of the statement:
RESQAPI(FILE, IERR)

or
BAT_RESQ

FILE

where:
Character FILE*260

Is the filename of Sequence Data Input file (input).

Integer IERR

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, error opening input file FILE.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-161

POWER FLOW APIS

RETIAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, no case in memory.
IERR = 2, error opening input file FILE.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-162

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

RNFIAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
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

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-163

POWER FLOW APIS

RWCMAPI

Power Technologies, Inc.

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

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).

Integer IERR

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid value of OPT.
IERR = 2, invalid value of OUT.
IERR = 3, error opening output file OFILE.
IERR = 4, working case inconsistent with IEEE common format.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-164

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

RWMANW

Power Technologies, Inc.

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

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

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

ALL = 1, process all buses.
ALL = 0, process only selected buses.

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

Is the output option selection.

OUT = 0, output to a data file specified by OFILE.
OUT = 1, output to the progress window.

Character OFILE*260 Is the output filename.

Integer IERR

PSS/E-29

Is the error return.

IERR = 0, no error.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.
IERR = 3, OUT is in error.
IERR = 4, unable to open OFILE.

GUIDE TO PSS/E BATCH COMMANDS

1-165

POWER FLOW APIS

RWMMAPI

Power Technologies, Inc.

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

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).

Integer IERR

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid value of OUT.
IERR = 2, error opening output file OFILE.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-166

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

RWSQNW

Power Technologies, Inc.

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

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

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

ALL = 1, process all buses.
ALL = 0, process only selected buses.

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(1), omit isolated buses.
STATUS(2), omit out-of-service branches.
STATUS(3), include subsystem data.
STATUS(4), include subsystem ties.

Integer OUT

Is the output option selection.

OUT = 0, output to a data file specified by OFILE.
OUT = 1, output to the progress window.

Character OFILE*260 Is the output filename.

Integer IERR

PSS/E-29

Is the error return.

IERR = 0, no error.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.
IERR = 3, OUT is in error.
IERR = 4, unable to open OFILE.
IERR = 5, no sequence data in the case.

GUIDE TO PSS/E BATCH COMMANDS

1-167

POWER FLOW APIS

SAVE_OPTION_SETTINGS_API

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

SAVENW

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, error opening SFILE.
IERR = 2, error writing to SFILE.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-169

POWER FLOW APIS

SCALNW

Power Technologies, Inc.

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

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

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

ALL = 1, process all buses.
ALL = 0, process only selected buses.

Integer APIOPT

Is the mode of operation in the API.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

SCALNW

Power Technologies, Inc.

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) = 0, no change.
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) = 0, all buses in subsystem.
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

GUIDE TO PSS/E BATCH COMMANDS

1-171

POWER FLOW APIS

SCALNW

Integer IERR

1-172

Power Technologies, Inc.

Is the error return.

IERR = 0, no error.
IERR = 1, either ALL or SID is in error.
IERR = 2, APIOPT is in error.
IERR = 3, STATUS is in error.
IERR = 4, generator/motor totals beyond limits.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

SCEQNW

Power Technologies, Inc.

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

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 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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.
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

GUIDE TO PSS/E BATCH COMMANDS

1-173

POWER FLOW APIS

SCGRAPI

Power Technologies, Inc.

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.

The API is invoked by the use of the statement:

CALL SCGRAPI(SID, ALL, APIOPT, STATUS, IERR, NERR)

or
BAT_SCGR

SID

ALL

APIOPT

STATUS(1) . . . STATUS(8)

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 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).

The values are as follows:
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, all buses in subsystem.
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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

SCGRAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, invalid STATUS value.
IERR = 3, specified faulted bus error.
IERR = 4, invalid APIOPT value.
IERR = 5, no sequence data in case.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-175

POWER FLOW APIS

SCMUAPI

Power Technologies, Inc.

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
API is invoked by the use of the statement:
CALL SCMUAPI(APIOPT, OPTIONS, RVAL, CKTARG, IERR, NERR)

or
BAT_SCMU
APIOPT
RVAL(5) CKTARG

OPTIONS(1) . . . OPTIONS(7)

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.
OPTIONS(1), double precision option.
OPTIONS(1) = 0, use single precision in calculating admittance matrix
terms.
OPTIONS(1) = 1, 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 transformer impedances.
OPTIONS(3) = 1, apply same factor used in the positive sequence to each
transformers zero sequence impedance.

1-176

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

SCMUAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, no case in memory.
IERR = 2, sequence data not in case.
IERR = 3, invalid OPTIONS value.
IERR = 4, invalid APIOPT value.
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

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-177

POWER FLOW APIS

SCMUAPI

Power Technologies, Inc.

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(2), bus to be faulted.

OPTIONS(3), faulted phase.
OPTIONS(3) = 1, phase A.
OPTIONS(3) = 2, phase B.
OPTIONS(3) = 3, phase C.

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(2), bus to be faulted.

OPTIONS(3), excluded phase.
OPTIONS(3) = 1, phase A.
OPTIONS(3) = 2, phase B.
OPTIONS(3) = 3, phase C.

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.
OPTIONS(4) = 1, phase A.
OPTIONS(4) = 2, phase B.
OPTIONS(4) = 3, phase C.

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.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

SCMUAPI

Power Technologies, Inc.

When APIOPT is 2 and OPTIONS(1) is 6, 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), excluded phase.
OPTIONS(4) = 1, phase A.
OPTIONS(4) = 2, phase B.
OPTIONS(4) = 3, phase C.

Real RVAL(5)

RVAL(1), resistance of the complex phase impedance in pu.

RVAL(2), reactance of the complex phase impedance in pu.

When APIOPT is 2 and OPTIONS(1) is 7, the following additional elements of OPTIONS and
RVAL are used.
Integer OPTIONS(7)

OPTIONS(2), bus to be faulted.

Real RVAL(5)

None.

When APIOPT is 2 and OPTIONS(1) is 8, the following additional elements of OPTIONS and
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) = 2, line-to-line or line-to-line-to-ground fault.
OPTIONS(5) = 3, three-phase.
OPTIONS(6), faulted (if OPTIONS(5) is 1) or excluded (if OPTIONS(5)
is 2) phase.
OPTIONS(6) = 1, phase A.
OPTIONS(6) = 2, phase B.
OPTIONS(6) = 3, phase C.
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

GUIDE TO PSS/E BATCH COMMANDS

1-179

POWER FLOW APIS

SCMUAPI

Real RVAL(5)

Power Technologies, Inc.

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

OPTIONS(5) is 2) fault impedance in pu.
RVAL(2), reactance of the complex L-G (if OPTIONS(5) is 1) or L-L (if
OPTIONS(5) is 2) fault impedance in pu.
RVAL(3), resistance of the complex L-G fault impedance in pu (if
OPTIONS(5) is 2).
RVAL(4), reactance of the complex L-G fault impedance in pu (if
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.

When APIOPT is 2 and OPTIONS(1) is 9, the following additional elements of OPTIONS and
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) = 1, line-to-ground.
OPTIONS(4) = 2, line-to-line or line-to-line-to-ground fault.
OPTIONS(4) = 3, three-phase.
OPTIONS(5), faulted (if OPTIONS(4) is 1) or excluded (if OPTIONS(4)
is 2) phase.
OPTIONS(5) = 1, phase A.
OPTIONS(5) = 2, phase B.
OPTIONS(5) = 3, phase C.

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) 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), fault location from bus OPTIONS(2) in pu of total line length.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

SCOPAPI

Power Technologies, Inc.

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.

The API is invoked by the use of the statement:

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.
ALL = 1, process all buses.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, ALL or SID (invalid value or subsystem SID not defined) is in
error.
IERR = 2, UNITS is in error.
IERR = 3, APIOPT is in error.
IERR = 4, no sequence data in case.
IERR = 5, initialization error.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-181

POWER FLOW APIS

SEQDAPI

Power Technologies, Inc.

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:
OPTIONS(1), double precision option.
OPTIONS(1) = 0, use single precision in calculating admittance matrix
terms.
OPTIONS(1) = 1, 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 transformer impedances.
OPTIONS(3) = 1, apply same factor used in the positive sequence to each
transformers zero sequence impedance.

Integer IERR

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, no case in memory.
IERR = 2, sequence data not in case.
IERR = 3, invalid OPTIONS value.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-182

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

SEQUENCE_NETWORK_SETUP_API

Power Technologies, Inc.

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

Is the value of the option setting (input if IOCODE is 0 or BAT_ command,

output if IOCODE is 1).
IVAL = 0, SCMU assumes SEQD has already been executed.
IVAL = 1, SCMU always executes activity SEQD.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-183

POWER FLOW APIS

SHNTNW

Power Technologies, Inc.

1.146 SHNTNW
This API is used to tabulate fixed and/or switched bus shunt contained in the working case. The API
is invoked by the use of the statement:
SHNTNW(SID, ALL, OPT, IERR)

or:
BAT_SHNT

SID

ALL

OPT

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 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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, OPT is in error.

1-184

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

SHORT_CIRCUIT_COORDINATES_API

Power Technologies, Inc.

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

Is the value of the option setting (input if IOCODE is 0 or BAT_ command,

output if IOCODE is 1).
IVAL = 0, rectangular.
IVAL = 1, polar.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-185

POWER FLOW APIS

SHORT_CIRCUIT_MODELING_API

Power Technologies, Inc.

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

Is the value of the option setting (input if IOCODE is 0 or BAT_ command,

output if IOCODE is 1).
IVAL = 0, center tapped two-phase.
IVAL = 1, normal three-phase.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-186

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

SHORT_CIRCUIT_UNITS_API

Power Technologies, Inc.

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

Is the value of the option setting (input if IOCODE is 0 or BAT_ command,

output if IOCODE is 1).
IVAL = 0, pu.
IVAL = 1, physical.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-187

POWER FLOW APIS

SHORT_CIRCUIT_WARNING_API

Power Technologies, Inc.

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".
The API is invoked by the use of the statement:
CALL SHORT_CIRCUIT_WARNING_API(IVAL, IOCODE, IERR, NERR)

or
BAT_SHORT_CIRCUIT_WARNING

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, disable printing of RESQ/TRSQ/solution warnings.
IVAL = 1, print RESQ/TRSQ/solution warnings.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-188

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

SHOWAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid OPTION value.
IERR = 2, FILE is blank when OPTION is 0.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-189

POWER FLOW APIS

SIZE_LEVEL_API

Power Technologies, Inc.

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

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-190

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

SIZEAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, no case in memory.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-191

POWER FLOW APIS

SOLVAPI

Power Technologies, Inc.

1.154 SOLVAPI
This API executes activity SOLV. This API uses the default element specification as described in
Section 1.1. The API is invoked by the use of the statement:
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:
OPTIONS(1), tap adjustment flag.
OPTIONS(1) = 0, disable.
OPTIONS(1) = 1, enable.
OPTIONS(2), area interchange adjustment flag.
OPTIONS(2) = 0, disable.
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), flat start flag.
OPTIONS(3) = 0, do not flat start.
OPTIONS(3) = 1, flat start.
OPTIONS(4), dc tap adjustment flag.
OPTIONS(4) = 0, disable.
OPTIONS(4) = 1, enable.
OPTIONS(5), switched shunt adjustment flag.
OPTIONS(5) = 0, disable.
OPTIONS(5) = 1, enable.
OPTIONS(6), var limit flag.
OPTIONS(6) = 0, apply var limits.
OPTIONS(6) = 1, ignore var limits.

1-192

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

SOLVAPI

Power Technologies, Inc.

Integer IERR

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid OPTIONS value.
IERR = 2, generators are "converted".
IERR = 3, working case has island without a swing bus.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-193

POWER FLOW APIS

SPCBAPI

Power Technologies, Inc.

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).

The values are as follows:
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) = 1, line-to-ground.
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).

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

SPCBAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, sequence data not in case.
IERR = 2, two phase option is enabled.
IERR = 3, bus not in case.
IERR = 4, unable to apply unbalance to branch specified.
IERR = 5, invalid OPTIONS value.
IERR = 6, invalid VALUES(1) value.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-195

POWER FLOW APIS

SPILAPI

Power Technologies, Inc.

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
(input). The values are as follows:
OPTIONS(1), base case rating set.
OPTIONS(1) = 1, RATEA.
OPTIONS(1) = 2, RATEB.
OPTIONS(1) = 3, RATEC.
OPTIONS(2), contingency case rating set.
OPTIONS(2) = 1, RATEA.
OPTIONS(2) = 2, RATEB.
OPTIONS(2) = 3, RATEC.
OPTIONS(3), base case line flow code.
OPTIONS(3) = 0, dc base case.
OPTIONS(3) = 1, ac base case.
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), list study system buses.
OPTIONS(5) = 0, no.
OPTIONS(5) = 1, yes.
OPTIONS(6), list opposing system buses.
OPTIONS(6) = 0, no.
OPTIONS(6) = 1, yes.
OPTIONS(7), list study system tie lines.
OPTIONS(7) = 0, no.
OPTIONS(7) = 1, yes.
OPTIONS(8), add study system tie lines to monitored line list.
OPTIONS(8) = 0, no.
OPTIONS(8) = 1, yes.
1-196

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

SPILAPI

Power Technologies, Inc.

OPTIONS(9), output format code.

OPTIONS(9) = 0, summary output.
OPTIONS(9) = 1, full output.
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(11) = 0, no.
OPTIONS(11) = 1, yes.
OPTIONS(12), convert MVA ratings to estimated MW ratings.
OPTIONS(12) = 0, no.
OPTIONS(12) = 1, yes.
OPTIONS(13), abort if MW mismatch exceeds TOLS(1).
OPTIONS(13) = 0, abort.
OPTIONS(13) = 1, continue.
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(1), required MW mismatch tolerance for continuing.
TOLS(2), percent of rating for reporting an element as overloaded.
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.
TOLS(7), study system generation shift.

Character LABELS*12 Is an array of eight elements specifying subsystem and interface labels
(input).
LABELS(1), study system label.
LABELS(2), opposing system label.
LABELS(3), interface label for optional interface limits summary table
(blank for none).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-197

POWER FLOW APIS

SPILAPI

Power Technologies, Inc.

LABELS(4), interface label for optional interface limits summary table

(blank for none).
LABELS(5), interface label for optional interface limits summary table
(blank for none).
LABELS(6), interface label for optional interface limits summary table
(blank for none.
LABELS(7), interface label for optional interface limits summary table
(blank for none).
LABELS(8), interface label for optional interface limits summary table
(blank for none).
Character DFXFILE*260 Is the name of Distribution Factor Data input file (input).
Character PRTFILE*260 Is the name of Subsystem Participation Data input file; blank for none
(input).
Integer IERR

Is the error return (output).

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 input file specified.
IERR = 5, subroutine GETLOS error (generators are "converted" or
swingless island present).
IERR = 6, subroutine INPROC error.
IERR = 7, same subsystem label specified for study and opposing
subsystems.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-198

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

SPLTAPI

Power Technologies, Inc.

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
the use of the statement:
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

Is the error return (output).

IERR = 0, no error occurred.
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

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-199

POWER FLOW APIS

SQEXNW

Power Technologies, Inc.

1.158 SQEXNW
This API is used to provide a tabulation of all fault analysis data pertaining to a selected bus. The
API is invoked by the use of the statement:
SQEXNW(SID, ALL, IERR)

or:
BAT_SQEX

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 = 0, no error occurred.
IERR = 1, either ALL or SID is in error.

1-200

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

SQLINW

Power Technologies, Inc.

1.159 SQLINW
This API is used to tabulate the sequence data in a form suitable for problem data documentation.
The API is invoked by the use of the statement:
SQLINW(SID, ALL, OPT, IERR)

or:
BAT_SQLI

SID

ALL

OPT

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 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
= 8, three-winding transformer

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, OPT is in error.
IERR = 3, no sequence data in the case.

GUIDE TO PSS/E BATCH COMMANDS

1-201

POWER FLOW APIS

STOPAPI

Power Technologies, Inc.

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.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

SUBSNW

Power Technologies, Inc.

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
use of the statement:
SUBSNW(SID, ALL, IERR)

or:
BAT_SUBS

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 = 0, no error occurred.
IERR = 1, either ALL or SID is in error.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-203

POWER FLOW APIS

SWITCHED_SHUNT_ADJUSTMENT_API

Power Technologies, Inc.

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

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.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-204

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

TAP_ADJUSTMENT_API

Power Technologies, Inc.

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

Is the value of the option setting (input if IOCODE is 0 or BAT_ command,

output if IOCODE is 1).
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

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-205

POWER FLOW APIS

TFLGNW

Power Technologies, Inc.

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

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 OPT

Is used to select the setting given to the transformers.

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

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, OPT is in error.

1-206

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

TIESNW

Power Technologies, Inc.

1.165 TIESNW
This API is used to tabulate the flows on all area tie lines, with tie flows grouped by area. The API
is invoked by the use of the statement:
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
subsystem must have been previously defined (input).

Integer ALL

Is the "all" areas or selected areas subsystem flag (input).

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

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-207

POWER FLOW APIS

TIEZNW

Power Technologies, Inc.

1.166 TIEZNW
This API is used to tabulate the flows on all zone tie lines, with tie flows grouped by zone. The API
is invoked by the use of the statement:
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
subsystem must have been previously defined (input).

Integer ALL

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

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

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.

1-208

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

TIMEAPI

Power Technologies, Inc.

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.

GUIDE TO PSS/E BATCH COMMANDS

1-209

POWER FLOW APIS

TLSTNW

Power Technologies, Inc.

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
use of the statement:
TLSTNW(SID, ALL, OPT, VREV, IERR)

or:
BAT_TLST

SID

ALL

OPT

VREV

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 OPT

Is used to select the type of transformers tabulated.

OPT = 0, all.
OPT = 1, violations only.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, OPT or VREV is in error.

1-210

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

TLTGAPI

Power Technologies, Inc.

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
OPTIONS(1) . . . OPTIONS(17)
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(1), base case rating set.
OPTIONS(1) = 1, RATEA.
OPTIONS(1) = 2, RATEB.
OPTIONS(1) = 3, RATEC.
OPTIONS(2), contingency case rating set.
OPTIONS(2) = 1, RATEA.
OPTIONS(2) = 2, RATEB.
OPTIONS(2) = 3, RATEC.
OPTIONS(3), base case line flow code.
OPTIONS(3) = 0, dc base case.
OPTIONS(3) = 1, ac base case.
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(5) = 1, include.
OPTIONS(6), list study system buses.
OPTIONS(6) = 0, no.
OPTIONS(6) = 1, yes.
OPTIONS(7), list opposing system buses.
OPTIONS(7) = 0, no.
OPTIONS(7) = 1, yes.
OPTIONS(8), list study system tie lines.
OPTIONS(8) = 0, no.
OPTIONS(8) = 1, yes.
PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-211

POWER FLOW APIS

TLTGAPI

Power Technologies, Inc.

OPTIONS(9), add study system tie lines to monitored line list.

OPTIONS(9) = 0, no.
OPTIONS(9) = 1, yes.
OPTIONS(10), output format code.
OPTIONS(1) = 0, summary output.
OPTIONS(1) = 1, full output.
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(12) = 0, no.
OPTIONS(12) = 1, yes.
OPTIONS(13), convert MVA ratings to estimated MW ratings.
OPTIONS(13) = 0, no.
OPTIONS(13) = 1, yes.
OPTIONS(14), abort if MW mismatch exceeds TOLS(1).
OPTIONS(14) = 0, abort.
OPTIONS(14) = 1, continue.
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(1), required MW mismatch tolerance for continuing.
TOLS(2), percent of rating for reporting an element as overloaded.
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.
TOLS(7), study system generation shift.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

TLTGAPI

Power Technologies, Inc.

Character LABELS*1

Is an array of eight elements specifying subsystem and interface labels

(input).
LABELS(1), study system label.
LABELS(2), opposing system label.
LABELS(3), interface label for optional interface limits summary table
(blank for none).
LABELS(4), interface label for optional interface limits summary table
(blank for none).
LABELS(5), interface label for optional interface limits summary table
(blank for none).
LABELS(6), interface label for optional interface limits summary table
(blank for none).
LABELS(7), interface label for optional interface limits summary table
(blank for none).
LABELS(8), interface label for optional interface limits summary table
(blank for none).

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

Is the error return (output).

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 input file specified.
IERR = 5, subroutine GETLOS error (generators are converted or
swingless island present).
IERR = 6, subroutine INPROC error.
IERR = 7, same subsystem label specified for study and opposing
subsystems.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-213

POWER FLOW APIS

TPCHNW

Power Technologies, Inc.

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

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 APIOPT

Is the mode of operation in the API.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

TPCHNW

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, APIOPT is in error.
IERR = 3, OPT is in error.
IERR = 4, bad THRSH(1) when APIOPT = 2 or bad THRSH(2) when
APIOPT = 3.
IERR = 5, no controlling transformers.
IERR = 6, STATUS is in error.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-215

POWER FLOW APIS

TRANSMISSION_LINE_UNITS_API

Power Technologies, Inc.

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

Is the value of the option setting (input if IOCODE is 0 or BAT_ command,

output if IOCODE is 1).
IVAL = 0, pu.
IVAL = 1, ohms/microfarads.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-216

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

TREEAPI

Power Technologies, Inc.

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.
The API is invoked by the use of the statement:
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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, no case in memory.
IERR = 2, invalid APIOPT value.
IERR = 3, invalid APIOPT 1 call (already made; need APIOPT 2 call).
IERR = 4, invalid APIOPT 2 call (no APIOPT 1 call).

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-217

POWER FLOW APIS

TYSLAPI

Power Technologies, Inc.

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

Is the error return (output).

IERR = 0, no error occurred.
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

Is the number of error entries in PBUF02 (output).

1-218

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

1-219

POWER FLOW APIS

VCHKNW

Power Technologies, Inc.

1.175 VCHKNW
This API is used to tabulate those buses whose voltage magnitude is outside a specified range. The
API is invoked by the use of the statement:
VCHKNW(SID, ALL, VLO, VHI, IERR)

or:
BAT_VCHK

SID

ALL

VLO

VHI

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.

Real VLO

Is the VMIN of the voltage band.

Real VHI

Is the VMAX of the voltage band.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, either VLO or VHI is in error.

1-220

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

VOLTAGE_INPUT_API

Power Technologies, Inc.

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
is invoked by the use of the statement:
CALL VOLTAGE_INPUT_API(IVAL, IOCODE, IERR, NERR)

or
BAT_VOLTAGE_INPUT_UNIT

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, pu.
IVAL = 1, kV.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-221

POWER FLOW APIS

VOLTAGE_OUTPUT_API

Power Technologies, Inc.

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
is invoked by the use of the statement:
CALL VOLTAGE_OUTPUT_API(IVAL, IOCODE, IERR, NERR)

or
BAT_VOLTAGE_OUTPUT_UNIT

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, pu.
IVAL = 1, kV.

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

Is the error return (output).

IERR = 0, no error occurred.
IERR = 1, invalid IVAL value.
IERR = 2, invalid IOCODE value.

Integer NERR

Is the number of error entries in PBUF02 (output).

1-222

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

POWER FLOW APIS

ZONENW

Power Technologies, Inc.

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

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" zones or selected subsystem flag (input).

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

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

1-223

POWER FLOW APIS

ZONMNW

Power Technologies, Inc.

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

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 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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.
IERR = 3, IZNEW not between 1 and ZONES.

1-224

GUIDE TO PSS/E BATCH COMMANDS

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)

Is an array of two elements. The values are as follows:

REALAR(1), desired area interchange.
REALAR(2), desired interchange tolerance.

Character NAMEAR*8 Is the area name.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = >0, errors occurred.
IERR = 1, invalid area number.
IERR = 2, no case in memory.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

2-1

LOAD FLOW DATA CHANGING APIS

Area Data

Power Technologies, Inc.

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.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

Owner Data

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, invalid owner number.
IERR = 2, no case in memory.
IERR = -1, warnings:
No equipment assigned to owner.

Integer NERR

PSS/E-29

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-3

LOAD FLOW DATA CHANGING APIS

Zone Data

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, invalid zone number.
IERR = 2, no case in memory.
IERR = -1, warnings:
No equipment assigned to zone.

Integer NERR

2-4

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

Bus Data

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, invalid bus number.
IERR = 2, bus table full.
IERR = 3, working case not initialized.
IERR = -1, warnings one or more of:
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

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-5

LOAD FLOW DATA CHANGING APIS

Non-Transformer Branch Data

Power Technologies, Inc.

2.5 Non-Transformer Branch Data

BRANCH_API(IARG, JARG, CKT, INTGAR, REALAR, IERR, NERR)

or
BAT_BRANCH_DATA
IARG
REALAR(1)...REALAR(15)

JARG

CKT

INTGAR(1)...INTGAR(6)

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

Non-Transformer Branch Data

Power Technologies, Inc.

Integer IERR

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, bus not found.
IERR = 2, circuit identifier is more than two characters.
IERR = 3, branch is a transformer.
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.
IERR = -1, warnings one or more of:
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

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-7

LOAD FLOW DATA CHANGING APIS

Two-Winding Transformer Data

Power Technologies, Inc.

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

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(15)

Is an array of fifteen elements. The values are as follows:

INTGAR(1), branch status (see Program Operation Manual,
Section 4.1.1.6, STAT).
INTGAR(2), metered end bus external number (IARG or JARG).
INTGAR(3), first owner number.
INTGAR(4), second owner number.
INTGAR(5), third owner number.
INTGAR(6), fourth owner number.
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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

Two-Winding Transformer Data

Power Technologies, Inc.

REALAR(9), rating set A line rating.

REALAR(10), rating set B line rating.
REALAR(11), rating set C line rating.
REALAR(12), first owner fraction.
REALAR(13), second owner fraction.
REALAR(14), third owner fraction.
REALAR(15), fourth owner fraction.
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

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, bus not found.
IERR = 2, circuit ID is more than two characters.
IERR = 3, branch is not a transformer.
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.
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.
IERR = -1, warnings one or more of:
Invalid metered end bus.
Invalid branch status.
No ownership data specified.
Invalid owner number.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

2-9

LOAD FLOW DATA CHANGING APIS

Two-Winding Transformer Data

Integer NERR

2-10

Power Technologies, Inc.

Invalid ownership factor.

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.

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

Three-Winding Transformer Data

Power Technologies, Inc.

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
invoked by the use of the statement:
THREE_WINDING_API(IARG, JARG, KARG, CKT, INTGAR, REALAR, NAMEAR,
IERR, NERR)

or:
BAT_THREE_WINDING_DATA
INTGAR(1)...INTGAR(17)

IARG
JARG
KARG
CKT
REALAR(1)...REALAR(41)
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

Is the bus number of another of the buses.

Character CKT*2

Is the transformer circuit identifier.

Integer INTGAR(17)

Is an array of seventeen elements. The values are as follows:

INTGAR(1), first owner number.
INTGAR(2), second owner number.
INTGAR(3), third owner number.
INTGAR(4), fourth owner number.
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(13), branch status (see Program Operation Manual,
Section 4.1.1.6, STAT).
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

GUIDE TO PSS/E BATCH COMMANDS

2-11

LOAD FLOW DATA CHANGING APIS

Three-Winding Transformer Data

Power Technologies, Inc.

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(30), first owner fraction.
REALAR(31), second owner fraction.
REALAR(32), third owner fraction.
REALAR(33), fourth owner fraction.
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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

Three-Winding Transformer Data

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
IERR = >0, errors occurred.
IERR = 1, bus not found.
IERR = 2, circuit identifier is more than two characters.
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 = 6, blank circuit identifier.
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.
IERR = -1, warnings one or more of:
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.

GUIDE TO PSS/E BATCH COMMANDS

2-13

LOAD FLOW DATA CHANGING APIS

Load Data

Power Technologies, Inc.

2.8 Load Data

LOAD_API(IARG,LDID,INTGAR,REALAR,IERR,NERR)

or
BAT_LOAD_DATA
IARG
REALAR(1)...REALAR(6)

LDID

INTGAR(1)...INTGAR(4)

where:
Integer IARG

Is the external bus number.

Character LDID*2

Is the load identifier.

Integer INTGAR(4)

Is an array of four elements. The values are as follows:

INTGAR(1), load status (see Program Operation Manual, Section 4.1.1.3,
STATUS).
INTGAR(2), area number.
INTGAR(3), zone number.
INTGAR(4), owner number.

Integer REALAR(6)

Is an array of six elements. The values are as follows:

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

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, bus not found.
IERR = 2, load identifier is more than two characters.
IERR = 3, blank load identifier is invalid.
IERR = 4, load table full.
IERR = -1, warnings one or more of:
Invalid load status.
Invalid area, zone or owner number.

Integer NERR

2-14

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

Plant Data

Power Technologies, Inc.

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)

Is an array of one element. The values are as follows:

INTGAR(1), remote bus number.

Integer REALAR(2)

Is an array of two elements. The values are as follows:

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

Integer IERR

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, bus not found.
IERR = 2, plant table full.
IERR = -1, warnings one or more of:
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

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-15

LOAD FLOW DATA CHANGING APIS

Machine Data

Power Technologies, Inc.

2.10 Machine Data

MACHINE_API(IARG, MCID, INTGAR, REALAR, IERR, NERR)

or
BAT_MACHINE_DATA
IARG
REALAR(1)...REALAR(16)

MCID

INTGAR(1)...INTGAR(5)

where:
Integer IARG

Is the external bus number.

Character MCID*2

Is the machine identifier.

Integer INTGAR(5)

Is an array of five elements. The values are as follows:

INTGAR(1), machine status (see Program Operation Manual,
Section 4.1.1.4, STAT).
INTGAR(2), first owner number.
INTGAR(3), second owner number.
INTGAR(4), third owner number.
INTGAR(5), fourth owner number.

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.
REALAR(13), first owner fraction.
REALAR(14), second owner fraction.
REALAR(15), third owner fraction.
REALAR(16), fourth owner fraction.

2-16

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

Machine Data

Power Technologies, Inc.

Integer IERR

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, bus not found.
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.
IERR = -1, warnings one or more of:
Invalid machine status.
Invalid ZSORCE: (0. 0.).
QMAX less than QMIN.
PMAX less than PMIN.
MBASE is not positive.
No ownership data.
Invalid owner number.
Invalid ownership factor.

Integer NERR

PSS/E-29

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-17

LOAD FLOW DATA CHANGING APIS

FACTS Device Data

Power Technologies, Inc.

2.11 FACTS Device Data

FACTS_API(KM, INTGAR, REALAR, IERR, NERR)

or
BAT_FACTS_DATA
KM
INTGAR(1)...INTGAR(4)
REALAR(1)...REALAR(12)

where:
Integer KM

Is the FACTS control device number (must be positive).

Integer INTGAR(4)

Is an array of four elements. The values are as follows:

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).
INTGAR(4), owner number.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

FACTS Device Data

Power Technologies, Inc.

Integer IERR

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, invalid facts device number.
IERR = 2, no case in memory.
IERR = 3, bus not found or no sending end bus specified.
IERR = 4, same bus specified for sending and terminal buses.
IERR = -1, warnings one or more of:
Invalid control mode.
Invalid owner number.
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

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-19

LOAD FLOW DATA CHANGING APIS

Two-Terminal dc Line Link Data

Power Technologies, Inc.

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
REALAR(1)...REALAR(8)
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:

INTGAR(1), control mode (see Program Operation Manual,
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

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, invalid dc line number.
IERR = 2, no case in memory.
IERR = 3, metrar is more than one character.
IERR = -1, warnings one or more of:
Invalid control mode.
Invalid line resistance.
Invalid compounding resistance.
Compounding resistance exceeds line resistance.

2-20

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

LOAD FLOW DATA CHANGING APIS

Two-Terminal dc Line Link Data

Scheduled voltage must exceed mode switch voltage.

Invalid metered end code.
Integer NERR

PSS/E-29

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-21

LOAD FLOW DATA CHANGING APIS

Two-Terminal dc Line Converter Data

Power Technologies, Inc.

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
INTGAR(1)...INTGAR(5)
REALAR(1)...REALAR(11)
CKTAR

where:
Integer CNVFLG

Is the converter type.

CNVFLG = 1, for rectifier data (X7RECT).
CNVFLG = 2, for inverter data (X7INVR).

Integer NDC

Is the dc line number (must be positive).

Integer INTGAR(5)

Is an array of five elements. The values are as follows:

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)

Is an array of fifteen elements. The values are as follows:

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

Two-Terminal dc Line Converter Data

Power Technologies, Inc.

Integer IERR

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, invalid dc line number.
IERR = 2, no case in memory.
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.
IERR = -1, warnings one or more of:
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

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-23

LOAD FLOW DATA CHANGING APIS

VSC dc Line Data

Power Technologies, Inc.

2.14 VSC dc Line Data

VSC_DC_LINE_API(NAMEAR, INTGAR, REALAR, IERR, NERR)

or
BAT_VSC_DC_LINE_DATA
REALAR(1)...REALAR(5)

NAMEAR

INTGAR(1)...INTGAR(5)

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
INTGAR(3), second owner number.
INTGAR(4), third owner number.
INTGAR(4), fourth owner number.

Integer REALAR(5)

Is an array of at least five elements. The values are as follows:

REALAR(1), dc line resistance.
REALAR(2), first owner fraction.
REALAR(3), second owner fraction.
REALAR(4), third owner fraction.
REALAR(5), fourth owner fraction.

Integer IERR

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, no case in memory.
IERR = 2, VSC dc line table full.
IERR = -1, warnings one or more of:
Invalid control mode.
Invalid line resistance.
Invalid owner number.
Invalid ownership factor.
No ownership data specified.

Integer NERR

2-24

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

VSC dc Line Converter Data

Power Technologies, Inc.

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,
INTGAR(1)...INTGAR(4)
REALAR(1)...REALAR(11)

where:
Character NAMEAR*8 Is the VSC dc line name.
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

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, IC is not 1 or 2.
IERR = 2, no case in memory.
IERR = 3, VSC dc line not in case.
IERR = 4, no converter bus specified or bus not found.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

2-25

LOAD FLOW DATA CHANGING APIS

VSC dc Line Converter Data

Power Technologies, Inc.

IERR = -1, warnings one or more of:

Converter bus is dummy bus of a multi-section line.
Invalid dc control code.
Invalid ac control code.
Remote bus not found.
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

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

Multi-Terminal dc Line

Power Technologies, Inc.

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

Is the dc line number (must be positive).

Integer INTGAR(8)

Is an array of eight elements. The values are as follows:

INTGAR(1), control mode (see Program Operation Manual,
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)

Is an array of one element. The values are as follows:

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

Integer IERR

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, invalid dc line number.
IERR = 2, no case in memory.
IERR = -1, warnings:
Invalid control mode.

Integer NERR

PSS/E-29

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-27

LOAD FLOW DATA CHANGING APIS

Multi-Terminal dc Line Converter Data

Power Technologies, Inc.

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
REALAR(1)...REALAR(13)

NDC

INTGAR(1)...INTGAR(4)

where:
Integer NDC

Is the dc line number (must be positive).

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

Multi-Terminal dc Line Converter Data

Power Technologies, Inc.

Integer IERR

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, invalid dc line number.
IERR = 2, no case in memory.
IERR = 3, no converter bus specified or bus not found.
IERR = 4, too many converters.
IERR = -1, warnings one or more of:
Converter bus is dummy bus of a multi-section line.
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

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-29

LOAD FLOW DATA CHANGING APIS

Multi-Terminal dc Line dc Bus Data

Power Technologies, Inc.

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

INTGAR(1)...INTGAR(5)

where:
Integer NDC

Is the dc line number (must be positive).

Integer IC

Is the dc bus number (must be positive).

Integer INTGAR(5)

Is an array of five elements. The values are as follows:

INTGAR(1), converter bus number or zero.
INTGAR(2), area number.
INTGAR(3), zone number.
INTGAR(4), owner number.
INTGAR(5), second dc bus number.

Integer REALAR(2)

Is an array of two elements. The values are as follows:

REALAR(1), resistance to ground.
REALAR(2), dc voltage (kV) (output only).

Character NAMEAR*8 Is the bus name.

Integer IERR

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, invalid dc line number.
IERR = 2, no case in memory.
IERR = 3, dc line not in case.
IERR = 4, invalid dc bus number.
IERR = -1, warnings one or more of:
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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

LOAD FLOW DATA CHANGING APIS

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

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-31

LOAD FLOW DATA CHANGING APIS

Multi-Terminal dc Line dc Link Data

Power Technologies, Inc.

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

Is the dc line number (must be positive).

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

Is the circuit identifier.

Integer INTGAR(1)

Is an array of one element. The values are as follows:

INTGAR(1), metered end dc bus number.

Integer REALAR(2)

Is an array of two elements. The values are as follows:

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

Integer IERR

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, invalid dc line number.
IERR = 2, no case in memory.
IERR = 3, dc line not in case.
IERR = 4, invalid dc bus number.
IERR = 5, circuit identifier is more than one character.
IERR = 6, branch from a bus to itself.
IERR = 7, too many dc links.
IERR = 8, dc bus not found in this multi-terminal dc line.
IERR = -1, warnings one or more of:
Invalid metered end bus.
Invalid RDC.
Invalid XDC.

Integer NERR

2-32

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

Switched Shunt Data

Power Technologies, Inc.

2.20 Switched Shunt Data

SWITCHED_SHUNT_API(IARG, INTGAR, REALAR, NAMEAR, IERR, NERR)

or
BAT_SWITCHED_SHUNT_DATA
REALAR(1)...REALAR(11)

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
INTGAR(3), number of steps for block 3.
INTGAR(4), number of steps for block 4.
INTGAR(5), number of steps for block 5.
INTGAR(6), number of steps for block 6.
INTGAR(7), number of steps for block 7.
INTGAR(8), number of steps for block 8.
INTGAR(9), control mode (see Program Operation Manual,
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(2), admittance increment per step for block 2.
REALAR(3), admittance increment per step for block 3.
REALAR(4), admittance increment per step for block 4.
REALAR(5), admittance increment per step for block 5.
REALAR(6), admittance increment per step for block 6.
REALAR(7), admittance increment per step for block 7.
REALAR(8), admittance increment per step for block 8.
REALAR(9), desired voltage upper limit.
REALAR(10), desired voltage lower limit.
REALAR(11), present switched shunt admittance.

Character NAMEAR*8 Is the VSC dc line name.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

2-33

LOAD FLOW DATA CHANGING APIS

Switched Shunt Data

Integer IERR

Power Technologies, Inc.

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, bus not found.
IERR = 2, switched shunt table full.
IERR = -1, warnings one or more of:
VSC dc line not found.
Remote bus not found.
Voltage controlling switched shunt specified as remotely regulating
itself.
Remote bus type code is not one.
Invalid control mode.
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

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

Multi-Section Line Data

Power Technologies, Inc.

2.21 Multi-Section Line Data

MULTI_SECTION_LINE_API(IARG, JARG, CKT, INTGAR, IERR, NERR)

or
BAT_MULTI_SECTION_LINE_DATA
INTGAR(1)...INTGAR(10)

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 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

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, bus not found.
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.
IERR = -1, warnings:
Invalid metered end bus.

Integer NERR
PSS/E-29

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-35

LOAD FLOW DATA CHANGING APIS

Multi-Section Line Edit

Power Technologies, Inc.

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

Is the bus number of "from" bus.

Integer JARG

Is the bus number of "to" bus.

Character CKT*2

Is the multi-section line identifier; CKT(1:1) must be&.

Integer INTGAR(2)

Is an array of two elements. The values are as follows:

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

Integer IERR

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, bus not found.
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.
IERR = -1, warnings one or more of:
Invalid metered end bus.
Invalid branch status.

Integer NERR

2-36

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

Transformer Impedance Correction Table Data

Power Technologies, Inc.

2.23 Transformer Impedance Correction Table Data

IMPEDANCE_CORRECTION_TABLE_API(I, INTGAR, REALAR, IERR, NERR)

or
BAT_IMPEDANCE_CORRECTION_TABLE_DATA
I
INTGAR(1)...INTGAR(2)
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)

Is an array of two elements. The values are as follows:

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

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, invalid table number.
IERR = 2, no case in memory.
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.
IERR = -1, warnings one or more of:
Point is beyond previous end of table.
Invalid scaling factor.

Integer NERR

PSS/E-29

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-37

LOAD FLOW DATA CHANGING APIS

Inter-Area Transfer Data

Power Technologies, Inc.

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)

Is an array of one element. The values are as follows:

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

Integer IERR

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, invalid area number.
IERR = 2, inter-area transfer identifier is more than one character.
IERR = 3, no case in memory.
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.
IERR = -1, warnings:
Changes to DESINT if "APPLYF" = 1.

Integer NERR

2-38

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

Solution Parameters

Power Technologies, Inc.

2.25 Solution Parameters

SOLUTION_PARAMETER_API(INTGAR, REALAR, IERR, NERR)

or
BAT_SOLUTION_PARAMETERS
REALAR(1)...REALAR(14)

INTGAR(1)...INTGAR(3)

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

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, no case in memory.
IERR = -1, warnings:
None.

Integer NERR

PSS/E-29

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-39

LOAD FLOW DATA CHANGING APIS

Change External Bus Number

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, bus IARG not found.
IERR = 2, invalid new bus number.
IERR = 3, bus newbus already assigned to another bus.
IERR = -1, warnings:
None.

Integer NERR

2-40

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

Two-Line Case Title Data

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, no case in memory.
IERR = -1, warnings:
None.

Integer NERR

PSS/E-29

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-41

LOAD FLOW DATA CHANGING APIS

Long Case Title Data

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, no case in memory.
IERR = -1, warnings:
None.

Integer NERR

2-42

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

Bus Sequence Data

Power Technologies, Inc.

2.29 Bus Sequence Data

SEQ_BUS_API(IARG, REALAR, IERR, NERR)

or
BAT_SEQ_BUS_DATA

IARG

REALAR(1)...REALAR(4)

where:
Integer IARG

Is the bus number.

Integer REALAR(4)

Is an array of four elements. The values are as follows:

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

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, sequence data not in case.
IERR = 2, bus not found.
IERR = -1, warnings:
None.

Integer NERR

PSS/E-29

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-43

LOAD FLOW DATA CHANGING APIS

Branch Sequence Data

Power Technologies, Inc.

2.30 Branch Sequence Data

SEQ_BRANCH_API(IARG, JARG, CKT, REALAR, IERR, NERR)

or
BAT_SEQ_BRANCH_DATA

IARG

JARG

CKT

REALAR(1)...REALAR(7)

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 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

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, sequence data not in case.
IERR = 2, bus not found.
IERR = 3, circuit identifier is more than two characters.
IERR = 4, circuit identifier starts with "&".
IERR = 5, branch not found.
IERR = 6, branch is a transformer.
IERR = -1, warnings:
Branch is Z.I.L., but zero-sequence impedance is non-zero.

Integer NERR

2-44

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

Two-Winding Transformer Sequence Data

Power Technologies, Inc.

2.31 Two-Winding Transformer Sequence Data

SEQ_TWO_WINDING_API(IARG, JARG, CKT, INTGAR, REALAR, IERR, NERR)

or
BAT_SEQ_TWO_WINDING_DATA
REALAR(1)...REALAR(4)

IARG

JARG

CKT

INTGAR(1)

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(1)

Is an array of one element. The values are as follows:

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

Integer REALAR(4)

Is an array of four elements. The values are as follows:

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

Integer IERR

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, sequence data not in case.
IERR = 2, bus not found.
IERR = 3, circuit identifier is more than two characters.
IERR = 4, circuit identifier starts with "&".
IERR = 5, branch not found.
IERR = 6, branch is not a transformer.
IERR = -1, warnings one or more of:
Invalid winding connection code.
Branch is not a Z.I.L. but zero-sequence impedance is zero.

Integer NERR

PSS/E-29

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-45

LOAD FLOW DATA CHANGING APIS

Three-Winding Transformer Sequence Data

Power Technologies, Inc.

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)
REALAR(1)...REALAR(8)

JARG

KARG

CKT

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

Is the bus number of another of the buses.

Character CKT*2

Is the transformer circuit identifier.

Integer INTGAR(1)

Is an array of one element. The values are as follows:

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

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, sequence data not in case.
IERR = 2, bus not found.
IERR = 3, circuit identifier is more than two characters.
IERR = 4, transformer not found.

2-46

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

LOAD FLOW DATA CHANGING APIS

Three-Winding Transformer Sequence Data

IERR = -1, warnings one or more of:

Invalid winding connection code.
Connection code is such that more than one-winding requires.
A grounding impedance.
Integer NERR

PSS/E-29

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-47

LOAD FLOW DATA CHANGING APIS

Machine Sequence Data

Power Technologies, Inc.

2.33 Machine Sequence Data

SEQ_MACHINE_API(IARG, MCID, REALAR, IERR, NERR)

or
BAT_SEQ_MACHINE_DATA

IARG

MCID

REALAR(1)...REALAR(6)

where:
Integer IARG

Is the bus number.

Character MDID*2

Is the machine identifier.

Integer REALAR(6)

Is an array of six elements. The values are as follows:

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

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, sequence data not in case.
IERR = 2, bus not found.
IERR = 3, machine identifier is more than two characters.
IERR = 4, machine not found.
IERR = -1, warnings:
None.

Integer NERR

2-48

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

LOAD FLOW DATA CHANGING APIS

Switched Shunt Zero-Sequence Data

Power Technologies, Inc.

2.34 Switched Shunt Zero-Sequence Data

SEQ_SWITCHED_SHUNT_API(IARG, REALAR, IERR, NERR)

or
BAT_SEQ_SWITCHED_SHUNT_DATA

IARG

REALAR(1)...REALAR(8)

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(2), zero-sequence increment per step for block 2.
REALAR(3), zero-sequence increment per step for block 3.
REALAR(4), zero-sequence increment per step for block 4.
REALAR(5), zero-sequence increment per step for block 5.
REALAR(6), zero-sequence increment per step for block 6.
REALAR(7), zero-sequence increment per step for block 7.
REALAR(8), zero-sequence increment per step for block 8.
REALAR(9), present zero-sequence switched shunt admittance (output
only).

Integer IERR

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, sequence data not in case.
IERR = 2, bus not found.
IERR = 3, no switched shunt at bus.
IERR = -1, warnings one or more of:
Block has N zero and B non-zero.
Block has admittances with different signs in.
Positive and zero-sequences.

Integer NERR

PSS/E-29

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-49

LOAD FLOW DATA CHANGING APIS

Zero-Sequence Mutual Coupling Data

Power Technologies, Inc.

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
REALAR(1)...REALAR(6)

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)

Is an array of six elements. The values are as follows:

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

Is the error return.

IERR = 0, no errors occurred.
IERR = >0, errors occurred.
IERR = 1, sequence data not in case.
IERR = 2, bus not found.
IERR = 3, circuit identifier is more than two characters.
IERR = 4, circuit identifier starts with "&".
IERR = 5, branch not found.
IERR = 6, mutual couples a branch to itself.
IERR = 7, branch is a transformer.
IERR = 8, branch is a zero impedance line.
IERR = 9, mutual table is full.

2-50

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

LOAD FLOW DATA CHANGING APIS

Zero-Sequence Mutual Coupling Data

IERR = -1, warnings one or more of:

Invalid B factor (<0.0 or >1.0).
B1 is not less than B2.
Integer NERR

PSS/E-29

The number of entries in PBUF02 containing error messages.

GUIDE TO PSS/E BATCH COMMANDS

2-51

This page intentionally left blank.

2-52

GUIDE TO PSS/E BATCH COMMANDS

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

GUIDE TO PSS/E BATCH COMMANDS

3-1

OPTIMAL POWER FLOW APIS

Active Power Dispatch Tables

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

Adjustable Branch Reactances

Power Technologies, Inc.

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)

or may be issued as the following batch command:

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

Is the circuit identifier.

Integer INTGAR(3)

Is an array of three integer elements. The value of each is as follows.

INTGAR(1) is the cost table 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 adjustable branch reactance status.
INTGAR(2) = 0, out of service.
INTGAR(2) = 1, in service.
INTGAR(3) is the cost table cross reference number.

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

Is the error return.

IERR = 0, no error occurred.
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

GUIDE TO PSS/E BATCH COMMANDS

3-3

OPTIMAL POWER FLOW APIS

Adjustable Branch Reactances

Power Technologies, Inc.

IERR = -1, non-fatal error occurred. Warning messages are as follows:

Invalid cost curve type specified.
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

The number of lines stored in the message buffer.

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)

or may be issued as the following batch command:

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.

ALL = 0, process only selected buses.
ALL = 1, process all buses.

Integer INTGAR(3)

Is an array of three integer elements. The value of each is as follows.

INTGAR(1) is the cost table 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 adjustable branch reactance status.
INTGAR(2) = 0, out of service.
INTGAR(2) = 1, in service.
INTGAR(3) is the cost table cross reference number.

Real REALAR(4)

3-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.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

Integer RVAL(4)

OPTIMAL POWER FLOW APIS

Adjustable Branch Reactances

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.
RVAL(2) indicates how the value of REALAR(2) should be used:
RVAL(2) = 0, if the value of REALAR(2) is to be used as defined.
RVAL(2) = 1, if the value of REALAR(2) is to be multiplied by the present
value of the maximum branch reactance multiplier.
RVAL(2) = 2, if the value of REALAR(2) is to be added to the present
value of the maximum branch reactance multiplier.
RVAL(3) indicates how the value of REALAR(3) should be used:
RVAL(3) = 0, if the value of REALAR(3) is to be used as defined.
RVAL(3) = 1, if the value of REALAR(3) is to be multiplied by the present
value of the minimum branch reactance multiplier.
RVAL(3) = 2, if the value of REALAR(3) is to be added to the present
value of the minimum branch reactance multiplier.
RVAL(4) indicates how the value of REALAR(4) should be used:
RVAL(4) = 0, if the value of REALAR(4) is to be used as defined.
RVAL(4) = 1, if the value of REALAR(4) is to be multiplied by the present
value of the cost scale coefficient.
RVAL(4) = 2, if the value of REALAR(4) is to be added to the present
value of the cost scale coefficient.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, ALL or SID is invalid.
IERR = 2, exceeded maximum number of allowable branch reactance
entries.
IERR = -1, non-fatal error occurred. Warning messages are as follows:
Invalid cost curve type specified.
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

The number of lines stored in the message buffer.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

3-5

OPTIMAL POWER FLOW APIS

Adjustable Bus Loads

Power Technologies, Inc.

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)

or may be issued as the following batch command:

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, invalid bus number specified.
IERR = 2, specified load does not exist.

Integer NERR

The number of lines stored in the message buffer.

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)

or may be issued as the following batch command:

BAT_OPF_LOAD_SUBSYS

SID

ALL

INTGAR(1)

INTGAR(2)

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.

ALL = 0, process only selected buses.
ALL = 1, process all buses, use existing data values.
ALL = 2, process all buses, use default data values.

3-6

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

Adjustable Bus Loads

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, ALL or SID value is invalid.

Integer NERR

The number of lines stored in the message buffer.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

3-7

OPTIMAL POWER FLOW APIS

Adjustable Bus Load Tables

Power Technologies, Inc.

3.5 Adjustable Bus Load Tables

The following API is used to add or modify adjustable bus load table records within the PSS/E
working file. The API is invoked through the subroutine call:
OPFLOD_TBL_API(TBL, INTGAR, REALAR, IERR, NERR)

or may be issued as the following batch command:

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)

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 adjustable bus load status.
INTGAR(2) = 0, out of service.
INTGAR(2) = 1, in service.
INTGAR(3) is the cost table cross reference number.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, exceeded maximum number of allowable load adjustment tables.
IERR = -1, non-fatal error occurred. Warning messages are as follows:
Invalid cost curve type specified.
Invalid load table status.
Maximum load multiplier less than minimum load multiplier.
Maximum load ratio multiplier less than minimum load ratio multiplier.

Integer NERR

The number of lines stored in the message buffer.

3-8

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

Adjustable Bus Shunts

Power Technologies, Inc.

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
the PSS/E working file. The API is invoked through the subroutine call:
OPFVAR_INDV_API(EIBUS, SHNTID, INTGAR, REALAR, IERR, NERR)

or is issued as the following batch command:

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)

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 and exponential curve.
INTGAR(1) = 2, piece-wise linear curve.
INTGAR(1) = 3, piece-wise quadratic curve.
INTGAR(2) is the status.
INTGAR(2) = 0, out of service.
INTGAR(2) = 1, in service.
INTGAR(3) is the cost table cross reference number.

Real REALAR(4)

Is an array of four real elements. The value of each is as follows.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, invalid bus number specified.
IERR = 2, invalid shunt identifier specified.
IERR = 3, exceeded maximum number of allowable adjustable bus shunt
entries.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

3-9

OPTIMAL POWER FLOW APIS

Adjustable Bus Shunts

Power Technologies, Inc.

IERR = -1, non-fatal error occurred. Possible warning messages are as

follows:
Invalid cost curve type specified.
Invalid adjustable bus shunt status specified.
Maximum shunt susceptance less than minimum shunt susceptance.
Integer NERR

The number of lines stored in the message buffer.

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)

or is issued as the following batch command:

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

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.

ALL = 0, process only selected buses.
ALL = 1, process all buses.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

Adjustable Bus Shunts

Power Technologies, Inc.

INTGAR(2) is the status.

INTGAR(2) = 0, out of service.
INTGAR(2) = 1, in service.
INTGAR(3) is the cost table cross reference number.
INTGAR(4) indicates which bus types should be processed.
INTGAR(4) = 0, all buses in subsystem.
INTGAR(4) = 1, only type 1 buses in subsystem.
INTGAR(4) = 2, only type 2 and 3 buses in subsystem.
Real REALAR(4)

Is an array of four real elements. The value of each is as follows.

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:
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 bus shunt susceptance.
RVAL(1) = 2, if the value of REALAR(1) is to be added to the present
value of the bus shunt susceptance.
RVAL(2) indicates how the value of REALAR(2) should be used:
RVAL(2) = 0, if the value of REALAR(2) is to be used as defined.
RVAL(2) = 1, if the value of REALAR(2) is to be multiplied by the present
value of the maximum bus shunt susceptance.
RVAL(2) = 2, if the value of REALAR(2) is to be added to the present
value of the maximum bus shunt susceptance.
RVAL(3) indicates how the value of REALAR(3) should be used:
RVAL(3) = 0, if the value of REALAR(3) is to be used as defined.
RVAL(3) = 1, if the value of REALAR(3) is to be multiplied by the present
value of the minimum bus shunt susceptance.
RVAL(3) = 2, if the value of REALAR(3) is to be added to the present
value of the minimum bus shunt susceptance.
RVAL(4) indicates how the value of REALAR(4) should be used:
RVAL(4) = 0, if the value of REALAR(4) is to be used as defined.
RVAL(4) = 1, if the value of REALAR(4) is to be multiplied by the present
value of the cost scale coefficient.
RVAL(4) = 2, if the value of REALAR(4) is to be added to the present
value of the cost scale coefficient.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

3-11

OPTIMAL POWER FLOW APIS

Adjustable Bus Shunts

Power Technologies, Inc.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
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 cost curve type specified.
Invalid adjustable bus shunt status specified.
Maximum shunt susceptance less than minimum shunt susceptance.

Integer NERR

The number of lines stored in the message buffer.

3-12

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

Branch Flow Constraints

Power Technologies, Inc.

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)

or may be issued as the following batch command:

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)

or may be issued as the following batch command:

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

Is the "from bus" number.

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

Is the "to bus" number.

Integer EKBUS

Is the "third bus" number, for specification of a three-winding transformer.

Character*2 CKTID

Is the circuit identifier.

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

GUIDE TO PSS/E BATCH COMMANDS

3-13

OPTIMAL POWER FLOW APIS

Branch Flow Constraints

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, invalid bus number specified.
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

The number of lines stored in the message buffer.

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)

or may be issued as the following batch command:

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)

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

Branch Flow Constraints

Power Technologies, Inc.

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.

ALL = 0, process only selected buses.
ALL = 1, process all buses.

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)

Is an array of three 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.
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.
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.
REALAR(5) is the soft limit penalty weight.

GUIDE TO PSS/E BATCH COMMANDS

3-15

OPTIMAL POWER FLOW APIS

Branch Flow Constraints

Integer RVAL(5)

Power Technologies, Inc.

Is an array of five 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 maximum normal flow limit.
RVAL(1) = 2, if the value of REALAR(1) is to be added to the present
value of the maximum normal flow limit.
RVAL(2) indicates how the value of REALAR(2) should be used:
RVAL(2) = 0, if the value of REALAR(2) is to be used as defined.
RVAL(2) = 1, if the value of REALAR(2) is to be multiplied by the present
value of the minimum normal flow limit.
RVAL(2) = 2, if the value of REALAR(2) is to be added to the present
value of the minimum normal flow limit.
RVAL(3) indicates how the value of REALAR(3) should be used:
RVAL(3) = 0, if the value of REALAR(3) is to be used as defined.
RVAL(3) = 1, if the value of REALAR(3) is to be multiplied by the present
value of the maximum emergency flow limit.
RVAL(3) = 2, if the value of REALAR(3) is to be added to the present
value of the maximum emergency flow limit.
RVAL(4) indicates how the value of REALAR(4) should be used:
RVAL(4) = 0, if the value of REALAR(4) is to be used as defined.
RVAL(4) = 1, if the value of REALAR(4) is to be multiplied by the present
value of the minimum emergency flow limit.
RVAL(4) = 2, if the value of REALAR(4) is to be added to the present
value of the minimum emergency flow limit.
RVAL(5) indicates how the value of REALAR(5) should be used:
RVAL(5) = 0, if the value of REALAR(5) is to be used as defined.
RVAL(5) = 1, if the value of REALAR(5) is to be multiplied by the present
value of the soft limit penalty weight.
RVAL(5) = 2, if the value of REALAR(5) is to be added to the present
value of the soft limit penalty weight.

Integer IERR

3-16

Is the error return.

IERR = 0, no error occurred.
IERR = 1, ALL or SID value is invalid.
IERR = 2, exceeded maximum number of allowable branch flow constraint entries.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

OPTIMAL POWER FLOW APIS

Branch Flow Constraints

IERR = -1, non-fatal error occurred. Possible warning messages are:

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

The number of lines stored in the message buffer.

GUIDE TO PSS/E BATCH COMMANDS

3-17

OPTIMAL POWER FLOW APIS

Bus Voltage Magnitude Constraints

Power Technologies, Inc.

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)

or may be issued as the following batch command:

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) = 0, reporting only.
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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, invalid bus number specified.

3-18

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

Bus Voltage Magnitude Constraints

Power Technologies, Inc.

IERR = -1, non-fatal error occurred. Warning messages are as follows:

Invalid limit type specified.
Maximum normal voltage limit less than minimum limit.
Maximum emergency voltage limit less than minimum limit.
Integer NERR

The number of lines stored in the message buffer.

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)

or may be issued as the following batch command:

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

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.

ALL = 0, process only selected buses.
ALL = 1, process all buses, use existing data values.
ALL = 2, process all buses, use default data values.

Integer INTGAR(3)

Is an array of three integer elements whose value is as follows.

INTGAR(1) is the limit type.
INTGAR(1) = 0, reporting only.
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).
INTGAR(3) indicates which bus types should be processed.
INTGAR(3) = 0, all buses in subsystem.
INTGAR(3) = 1, only type 1 buses in subsystem.
INTGAR(3) = 2, only type 2 and 3 buses in subsystem.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

3-19

OPTIMAL POWER FLOW APIS

Bus Voltage Magnitude Constraints

Power Technologies, Inc.

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 RVAL(5)

Is an array of five 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 normal bus voltage minimum limit.
RVAL(1) = 2, if the value of REALAR(1) is to be added to the present
value of the normal bus voltage minimum limit.
RVAL(2) indicates how the value of REALAR(2) should be used:
RVAL(2) = 0, if the value of REALAR(2) is to be used as defined.
RVAL(2) = 1, if the value of REALAR(2) is to be multiplied by the present
value of the normal bus voltage maximum limit.
RVAL(2) = 2, if the value of REALAR(2) is to be added to the present
value of the normal bus voltage maximum limit.
RVAL(3) indicates how the value of REALAR(3) should be used:
RVAL(3) = 0, if the value of REALAR(3) is to be used as defined.
RVAL(3) = 1, if the value of REALAR(3) is to be multiplied by the present
value of the emergency bus voltage minimum limit.
RVAL(3) = 2, if the value of REALAR(3) is to be added to the present
value of the emergency bus voltage minimum limit.
RVAL(4) indicates how the value of REALAR(4) should be used:
RVAL(4) = 0, if the value of REALAR(4) is to be used as defined.
RVAL(4) = 1, if the value of REALAR(4) is to be multiplied by the present
value of the emergency bus voltage maximum limit.
RVAL(4) = 2, if the value of REALAR(4) is to be added to the present
value of the emergency bus voltage maximum limit.
RVAL(5) indicates how the value of REALAR(5) should be used:
RVAL(5) = 0, if the value of REALAR(5) is to be used as defined.
RVAL(5) = 1, if the value of REALAR(5) is to be multiplied by the present
value of the soft limit penalty weight.
RVAL(5) = 2, if the value of REALAR(5) is to be added to the present
value of the soft limit penalty weight.

3-20

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

OPTIMAL POWER FLOW APIS

Bus Voltage Magnitude Constraints

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, ALL or SID value is invalid.
IERR = -1, non-fatal error occurred. Warning messages are as follows:
Invalid limit type specified.
Maximum normal voltage limit less than minimum limit.
Maximum emergency voltage limit less than minimum limit.

Integer NERR

The number of lines stored in the message buffer.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

3-21

OPTIMAL POWER FLOW APIS

Cost Curve Tables

Power Technologies, Inc.

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)

or may be issued as the following batch command:

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

Is the error return.

IERR = 0, no error occurred.
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

The number of lines stored in the message buffer.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

Cost Curve Tables

Power Technologies, Inc.

or may be issued as the following batch command:

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

Is the cost table description of, at most, 12 characters.

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

Is the error return.

IERR = 0, no error occurred.
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

The number of lines stored in the message buffer.

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
working file. The API is invoked through the subroutine call:
CSTTBL_POLY_API(TBL, LABL, REALAR, LINCST, QUACST, EXPCST, EXPON,
IERR, NERR)

or may be issued as the following batch command:

BAT_OPF_CSTTBL_POLY
EXPON

PSS/E-29

TBL LABL REALAR(1) LINCST QUACST EXPCST

GUIDE TO PSS/E BATCH COMMANDS

3-23

OPTIMAL POWER FLOW APIS

Cost Curve Tables

Power Technologies, Inc.

where:
Integer TBL

Is the polynomial and exponential cost curve table number.

Character*12 LABL

Is the cost table description of, at most, 12 characters.

Real REALAR(1)

Is an array of one integer element whose value is as follows.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, exceeded maximum number of allowable cost tables.
IERR = 2, exceeded maximum number of allowable cost curve data
values.

Integer NERR

The number of lines stored in the message buffer.

3-24

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

Generator Dispatch Data

Power Technologies, Inc.

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
working file. The API is invoked through the subroutine call:
GENDSP_INDV_API(EIBUS, GENID, INTGAR, REALAR, IERR, NERR)

or may be issued as the following batch command:

BAT_OPF_GENDSP_INDV

EIBUS GENID REALAR(1) INTGAR(1)

where:
Integer EIBUS

Is the bus number.

Character*2 GENID

Is the machine identifier.

Integer INTGAR(1)

Is an array of one integer element whose value is as follows.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, invalid bus number specified.
IERR = 2, specified machine does not exist.

Integer NERR

The number of lines stored in the message buffer.

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

Is a valid subsystem ID. Valid subsystem IDs range from 0 to 3. A subsystem must have been previously defined.

GUIDE TO PSS/E BATCH COMMANDS

3-25

OPTIMAL POWER FLOW APIS

Generator Dispatch Data

Power Technologies, Inc.

Integer ALL

Is the "all" buses or selected subsystem flag.

ALL = 0, process only selected buses.
ALL = 1, process all buses, use existing data values.
ALL = 2, process all buses, use default data values.

Integer INTGAR(1)

Is an array of one integer element whose value is as follows.

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 RVAL(1)

Is an array of one integer element. The value of the 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 dispatch fraction.
RVAL(1) = 2, if the value of REALAR(1) is to be added to the present
value of the dispatch fraction.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, ALL or SID value is invalid.

Integer NERR

The number of lines stored in the message buffer.

3-26

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

Generation Reactive Capability Data

Power Technologies, Inc.

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)

or may be issued as the following batch command:

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

Is the machine identifier.

Integer INTGAR(1)

Is an array of one integer element whose value is as follows.

INTGAR(1) is the reactive capability limit status:
INTGAR(1) = 0, out of service.
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)

Is an array of five real elements whose value is as follows.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, invalid bus number specified.
IERR = 2, exceeded maximum number of allowable reactive capability
records.
IERR = 3, specified machine does not exist.
IERR = -1, non-fatal error occurred. Possible warning messages are:
Invalid reactive capability status specified.

Integer NERR

The number of lines stored in the message buffer.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

3-27

OPTIMAL POWER FLOW APIS

Generation Reactive Capability Data

Power Technologies, Inc.

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)

or may be issued as the following batch command:

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

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.

ALL = 0, process only selected buses.
ALL = 1, process all buses.

Integer INTGAR(1)

Is an array of one integer element whose value is as follows.

INTGAR(1) is the reactive capability limit status:
INTGAR(1) = 0, out of service.
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)

Is an array of five real elements whose value is as follows.

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)

Is an array of five 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 direct-axis synchronous reactance.
RVAL(1) = 2, if the value of REALAR(1) is to be added to the present
value of the direct-axis synchronous reactance.

3-28

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

OPTIMAL POWER FLOW APIS

Generation Reactive Capability Data

RVAL(2) indicates how the value of REALAR(2) should be used:

RVAL(2) = 0, if the value of REALAR(2) is to be used as defined.
RVAL(2) = 1, if the value of REALAR(2) is to be multiplied by the present
value of the stator current limit.
RVAL(2) = 2, if the value of REALAR(2) is to be added to the present
value of the stator current limit.
RVAL(3) indicates how the value of REALAR(3) should be used:
RVAL(3) = 0, if the value of REALAR(3) is to be used as defined.
RVAL(3) = 1, if the value of REALAR(3) is to be multiplied by the present
value of the rated lagging power factor.
RVAL(3) = 2, if the value of REALAR(3) is to be added to the present
value of the rated lagging power factor.
RVAL(4) indicates how the value of REALAR(4) should be used:
RVAL(4) = 0, if the value of REALAR(4) is to be used as defined.
RVAL(4) = 1, if the value of REALAR(4) is to be multiplied by the present
value of the rated leading power factor.
RVAL(4) = 2, if the value of REALAR(4) is to be added to the present
value of the rated leading power factor.
RVAL(5) indicates how the value of REALAR(5) should be used:
RVAL(5) = 0, if the value of REALAR(5) is to be used as defined.
RVAL(5) = 1, if the value of REALAR(5) is to be multiplied by the present
value of the maximum reactive absorption.
RVAL(5) = 2, if the value of REALAR(5) is to be added to the present
value of the maximum reactive absorption.
Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, ALL or SID value is invalid.
IERR = 2, exceeded maximum number of allowable reactive capability
records.
IERR = -1, non-fatal error occurred. Possible warning messages are:
Invalid reactive capability status specified.

Integer NERR

The number of lines stored in the message buffer.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

3-29

OPTIMAL POWER FLOW APIS

Generation Reserve Data

Power Technologies, Inc.

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)

or may be issued as the following batch command:

BAT_OPF_GENRSV_INDV

EIBUS GENID REALAR(1) REALAR(2)

where:
Integer EIBUS

Is the bus number.

Character*2 GENID

Is the machine identifier.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, invalid bus number specified.
IERR = 2, exceeded maximum number of allowable generator reserve
entries.
IERR = 3, specified machine does not exist.

Integer NERR

The number of lines stored in the message buffer.

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)

or may be issued as the following batch command:

BAT_OPF_GENRSV_SUBSYS
RVAL(1)
RVAL(2)

SID

ALL

REALAR(1) REALAR(2)

where:
Integer SID

3-30

Is a valid subsystem ID. Valid subsystem IDs range from 0 to 3. A subsystem must have been previously defined.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

Generation Reserve Data

Power Technologies, Inc.

Integer ALL

Is the "all" buses or selected subsystem flag.

ALL = 0, process only selected buses.
ALL = 1, process all buses.

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 RVAL(2)

Is an array of two 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 unit ramp rate.
RVAL(1) = 2, if the value of REALAR(1) is to be added to the present
value of the unit ramp rate.
RVAL(2) indicates how the value of REALAR(2) should be used:
RVAL(2) = 0, if the value of REALAR(2) is to be used as defined.
RVAL(2) = 1, if the value of REALAR(2) is to be multiplied by the present
value of the unit capability.
RVAL(2) = 2, if the value of REALAR(2) is to be added to the present
value of the unit capability.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, ALL or SID value is invalid.
IERR = 2, exceeded maximum number of allowable generator reserve
entries.

Integer NERR

The number of lines stored in the message buffer.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

3-31

OPTIMAL POWER FLOW APIS

Interface Flow Constraints

Power Technologies, Inc.

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
working file. The API is invoked through the subroutine call:
INTFLW_MAIN_API(IFID, LABL, INTGAR, REALAR, IERR, NERR)

or is issued as the following batch command:

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(1) = 2, Mvar.
INTGAR(2) is the interface flow limit type.
INTGAR(2) = 0, reporting only.
INTGAR(2) = 1, hard limit.
INTGAR(2) = 2, linear soft limit.
INTGAR(2) = 3, quadratic soft limit.

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.
REALAR(3) is the soft limit penalty weight.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, exceeded maximum number of allowable interface flow constraint entries.
IERR = -1, non-fatal error occurred. Possible warning messages are:
Maximum interface flow is less than the minimum interface flow.
Invalid flow type specified.
Invalid interface flow limit type specified.

Integer NERR

The number of lines stored in the message buffer.

3-32

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

Interface Flow Constraints

Power Technologies, Inc.

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)

or may be issued as the following batch command:

BAT_OPF_INTFLW_RESET

IFID

where:
Integer IFID

Is the interface flow identifier.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, invalid interface flow identifier specified.

Integer NERR

The number of lines stored in the message buffer.

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)

or may be issued as the following batch command:

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)

or may be issued as the following batch command:

BAT_OPF_INTFLW_3WT

IFID EIBUS EJBUS EKBUS CKTID

where:
Integer IFID

Is the interface flow identifier.

Integer EIBUS

Is the "from bus" number.

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

GUIDE TO PSS/E BATCH COMMANDS

3-33

OPTIMAL POWER FLOW APIS

Interface Flow Constraints

Power Technologies, Inc.

Integer EJBUS

Is the "to bus" number.

Integer EKBUS

Is the "third bus" number.

Character*2 CKTID

Is the circuit identifier.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, exceeded maximum number of allowable participating branch
entries.
IERR = 2, invalid interface flow identifier specified.
IERR = 3, invalid bus number specified.
IERR = 4, specified branch/three-winding transformer does not exist.
IERR = 5, specified branch/winding is already participating in the
interface.

Integer NERR

The number of lines stored in the message buffer.

3-34

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

Linear Constraint Dependencies

Power Technologies, Inc.

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)

or may be issued as the following batch command:

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)

Is an array of two real elements whose value is as follows.

REALAR(1) is the maximum constraint slack value.
REALAR(2) is the minimum constraint slack value.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, exceeded maximum number of allowable linear constraint
dependency equations.
IERR = -1, non-fatal error occurred. Possible warning messages are:
Maximum linear constraint slack is less than the minimum linear constraint slack.

Integer NERR

The number of lines stored in the message buffer.

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)

or may be issued as the following batch command:

BAT_OPF_LNCEQN_RESET

IQID

where:
Integer IQID

PSS/E-29

Is the linear constraint equation identification number.

GUIDE TO PSS/E BATCH COMMANDS

3-35

OPTIMAL POWER FLOW APIS

Linear Constraint Dependencies

Power Technologies, Inc.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, Invalid linear constraint identifier specified.

Integer NERR

The number of lines stored in the message buffer.

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.
The API is invoked through the subroutine call:
LNCEQN_VMAG_API(IQID, EIBUS, REALAR, IERR, NERR)

or may be issued as the following batch command:

BAT_OPF_LNCEQN_VMAG

IQID EIBUS REALAR(1)

where:
Integer IQID

Is the linear constraint equation identification number.

Integer EIBUS

Is the bus number.

Real REALAR(1)

Is an array of one real element whose value is as follows.

REALAR(1) is the value of the coefficient associated with the equation
variable.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, specified linear constraint equation does not exist.
IERR = 2, exceeded maximum number of allowable participating equation
variables.
IERR = 3, invalid bus number specified.

Integer NERR

The number of lines stored in the message buffer.

3-36

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

Linear Constraint Dependencies

Power Technologies, Inc.

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)

or may be issued as the following batch command:

BAT_OPF_LNCEQN_VANG

IQID EIBUS REALAR(1)

where:
Integer IQID

Is the linear constraint equation identification number.

Integer EIBUS

Is the bus number.

Real REALAR(1)

Is an array of one real element whose value is as follows.

REALAR(1) is the value of the coefficient associated with the equation
variable.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, specified linear constraint equation does not exist.
IERR = 2, exceeded maximum number of allowable participating equation
variables.
IERR = 3, invalid bus number specified.

Integer NERR

The number of lines stored in the message buffer.

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)

or may be issued as the following batch command:

BAT_OPF_LNCEQN_PGEN

IQID ITBL REALAR(1)

where:
Integer IQID

Is the linear constraint equation identification number.

Integer ITBL

Is the active power dispatch table number.

Real REALAR(1)

Is an array of one real element whose value is as follows.

REALAR(1) is the value of the coefficient associated with the equation
variable.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

3-37

OPTIMAL POWER FLOW APIS

Linear Constraint Dependencies

Power Technologies, Inc.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, specified linear constraint equation does not exist.
IERR = 2, exceeded maximum number of allowable participating equation
variables.
IERR = 3, invalid active power dispatch table number specified.

Integer NERR

The number of lines stored in the message buffer.

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)

or may be issued as the following batch command:

BAT_OPF_LNCEQN_QGEN

IQID EIBUS GENID REALAR(1)

where:
Integer IQID

Is the linear constraint equation identification number.

Integer EIBUS

Is the bus number.

Character*2 GENID

Is the machine identifier.

Real REALAR(1)

Is an array of one real element whose value is as follows.

REALAR(1) is the value of the coefficient associated with the equation
variable.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, specified linear constraint equation does not exist.
IERR = 2, exceeded maximum number of allowable participating equation
variables.
IERR = 3, specified bus does not exist.
IERR = 4, specified machine does not exist.

Integer NERR

The number of lines stored in the message buffer.

3-38

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

Linear Constraint Dependencies

Power Technologies, Inc.

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
the PSS/E working file. The API is invoked through the subroutine call:
LNCEQN_TRAN_API(IQID, EIBUS, EJBUS, EKBUS, CKTID, REALAR, IERR,
NERR)

or may be issued as the following batch command:

BAT_OPF_LNCEQN_TRAN

IQID EIBUS EJBUS EKBUS CKTID REALAR(1)

where:
Integer IQID

Is the linear constraint equation identification number.

Integer EIBUS

Is the "from bus" number.

Integer EJBUS

Is the "to bus" number.

Integer EKBUS

Is the "third bus" number if a three-winding transformer is specified and

zero for a two-winding transformer.

Character*2 CKTID

Is the circuit identifier.

Real REALAR(1)

Is an array of one real element whose value is as follows.

REALAR(1) is the value of the coefficient associated with the equation
variable.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, specified linear constraint equation does not exist.
IERR = 2, exceeded maximum number of allowable participating equation
variables.
IERR = 3, invalid bus number specified.
IERR = 4, specified branch/transformer does not exist.
IERR = 5, specified branch is not a transformer.

Integer NERR

The number of lines stored in the message buffer.

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
invoked through the subroutine call:
LNCEQN_BRFLOW_API(IQID, EIBUS, EJBUS, EKBUS, CKTID, FLWID, REALAR,
IERR, NERR)

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

3-39

OPTIMAL POWER FLOW APIS

Linear Constraint Dependencies

Power Technologies, Inc.

or may be issued as the following batch command:

BAT_OPF_LNCEQN_BRFLW
REALAR(1)

IQID EIBUS EJBUS EKBUS CKTID FLWID

where:
Integer IQID

Is the linear constraint equation identification number.

Integer EIBUS

Is the "from bus" number.

Integer EJBUS

Is the "to bus" number.

Integer EKBUS

Is the "third bus" number for a three-winding transformer and zero for a
two-winding transformer.

Character*2 CKTID

Is the circuit identifier.

Character*1 FLWID

Is the branch flow identifier.

Real REALAR(1)

Is an array of one real element whose value is as follows.

REALAR(1) is the value of the coefficient associated with the equation
variable.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, specified linear constraint equation does not exist.
IERR = 2, exceeded maximum number of allowable participating equation
variables.
IERR = 3, invalid bus number specified.
IERR = 4, specified branch/transformer does not exist.
IERR = 5, specified branch flow does not exist.

Integer NERR

The number of lines stored in the message buffer.

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)

or may be issued as the following batch command:

BAT_OPF_LNCEQN_INFLW

IQID ITBL REALAR(1)

where:
Integer IQID

3-40

Is the linear constraint equation identification number.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

Linear Constraint Dependencies

Power Technologies, Inc.

Integer ITBL

Is the interface flow identifier.

Real REALAR(1)

Is an array of one real element whose value is as follows.

REALAR(1) is the value of the coefficient associated with the equation
variable.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, specified linear constraint equation does not exist.
IERR = 2, exceeded maximum number of allowable participating equation
variables.
IERR = 3, invalid interface flow identifier specified.

Integer NERR

The number of lines stored in the message buffer.

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
invoked through the subroutine call:
LNCEQN_ADJVAR_API(IQID, EIBUS, SHNTID, REALAR, IERR, NERR)

or may be issued as the following batch command:

BAT_OPF_LNCEQN_ADJVR

IQID EIBUS SHNTID REALAR(1)

where:
Integer IQID

Is the linear constraint equation identification number.

Integer EIBUS

Is the bus number.

Character*1 SHNTID

Is the bus shunt identifier.

Real REALAR(1)

Is an array of one real element whose value is as follows.

REALAR(1) is the value of the coefficient associated with the equation
variable.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, specified linear constraint equation does not exist.
IERR = 2, exceeded maximum number of allowable participating equation
variables.
IERR = 3, invalid bus number specified.
IERR = 4, specified adjustable bus shunt does not exist.

Integer NERR

The number of lines stored in the message buffer.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

3-41

OPTIMAL POWER FLOW APIS

Linear Constraint Dependencies

Power Technologies, Inc.

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
through the subroutine call:
LNCEQN_SWSHUNT_API(IQID, EIBUS, REALAR, IERR, NERR)

or may be issued as the following batch command:

BAT_OPF_LNCEQN_SWSHN

IQID EIBUS REALAR(1)

where:
Integer IQID

Is the linear constraint equation identification number.

Integer EIBUS

Is the bus number.

Real REALAR(1)

Is an array of one real element whose value is as follows.

REALAR(1) is the value of the coefficient associated with the equation
variable.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, specified linear constraint equation does not exist.
IERR = 2, exceeded maximum number of allowable participating equation
variables.
IERR = 3, invalid bus number specified.

Integer NERR

The number of lines stored in the message buffer.

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
invoked through the subroutine call:
LNCEQN_ADJLOAD_API(IQID, ITBL, REALAR, IERR, NERR)

or is issued as the following batch command:

BAT_OPF_LNCEQN_ADJLD

IQID ITBL REALAR(1)

where:
Integer IQID

Is the linear constraint equation identification number.

Integer ITBL

Is the adjustable bus load table identifier.

3-42

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

OPTIMAL POWER FLOW APIS

Linear Constraint Dependencies

Real REALAR(1)

Is an array of one real element whose value is as follows.

REALAR(1) is the value of the coefficient associated with the equation
variable.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, specified linear constraint equation does not exist.
IERR = 2, exceeded maximum number of allowable participating equation
variables.
IERR = 3, specified adjustable bus load table does not exist.

Integer NERR

The number of lines stored in the message buffer.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

3-43

OPTIMAL POWER FLOW APIS

List OPF Data (LSTONW)

Power Technologies, Inc.

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)

or is issued as the following batch command:

BAT_LSTO

SID

ALL

OPT

VREV

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.

ALL = 1, process all buses.
ALL = 0, process only selected buses.

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

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, OPT or VREV is in error.
IERR = 3, no OPF data in the case.

3-44

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

OPF Solution (NOPFNW)

Power Technologies, Inc.

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
through the subroutine call:
NOPFNW(SID, ALL, IERR, NERR)

or is issued as the following batch command:

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

Is the "all" buses or selected subsystem flag.

ALL = 0, process only selected buses.
ALL = 1, process all buses.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, SID is not valid.
IERR = 2, OPT is in error.

Integer NERR

The number of lines stored in the message buffer.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

3-45

OPTIMAL POWER FLOW APIS

OPF Solution Options (OPTONW)

Power Technologies, Inc.

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)

or is issued as the following batch command:

BAT_OPTO
SID
OPFILE RCFILE

ALL

IARY(1) IARY(36)

RARY(1) RARY(19)

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

Is the "all" buses or selected subsystem flag.

ALL = 0, process only selected buses.
ALL = 1, process all buses.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

OPTIMAL POWER FLOW APIS

OPF Solution Options (OPTONW)

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

GUIDE TO PSS/E BATCH COMMANDS

3-47

OPTIMAL POWER FLOW APIS

OPF Solution Options (OPTONW)

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

OPTIMAL POWER FLOW APIS

OPF Solution Options (OPTONW)

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.

GUIDE TO PSS/E BATCH COMMANDS

3-49

OPTIMAL POWER FLOW APIS

OPF Solution Options (OPTONW)

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, SID is not valid.
IERR = 2, OPT is in error.
IERR = 3, IARY or RARY data error.

Integer NERR

The number of lines stored in the message buffer.

3-50

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

Period Reserve Constraints

Power Technologies, Inc.

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.
The API is invoked through the subroutine call:
PERRSV_MAIN_API(RSVID, INTGAR, REALAR, IERR, NERR)

or is issued as the following batch command:

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)

Is an array of one integer element whose value is as follows.

INTGAR(1) is the status of the period reserve constraint.
INTGAR(1) = 0, out of service.
INTGAR(1) = 1, in service.

Real REALAR(2)

Is an array of two real elements whose value is as follows.

REALAR(1) is the reserve limit, in MW.
REALAR(2) is the period, in minutes.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, invalid period reserve identifier specified.
IERR = -1, non-fatal error occurred. Possible warning messages are:
Invalid period reserve status specified.

Integer NERR

The number of lines stored in the message buffer.

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)

or is issued as the following batch command:

BAT_OPF_PERRSV_RESET

RSVID

where:
Integer RSVID

PSS/E-29

Is the period reserve identifier (1 through 15).

GUIDE TO PSS/E BATCH COMMANDS

3-51

OPTIMAL POWER FLOW APIS

Period Reserve Constraints

Power Technologies, Inc.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, invalid period reserve identifier specified.

Integer NERR

The number of lines stored in the message buffer.

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)

or may be issued as the following batch command:

BAT_OPF_PERRSV_GEN

RSVID EIBUS GENID

where:
Integer RSVID

Is the period reserve identifier (1 through 15).

Integer EIBUS

Is the bus number.

Character*2 GENID

Is the machine identifier.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, invalid period reserve identifier specified.
IERR = 2, invalid bus number specified.
IERR = 3, specified machine does not exist.
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

The number of lines stored in the message buffer.

3-52

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

Read Optimal Power Flow Data File

Power Technologies, Inc.

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)

or is issued as the following batch command:

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

Is the error return.

IERR = 0, no error.
IERR = 1, problem encountered while opening file.

GUIDE TO PSS/E BATCH COMMANDS

3-53

OPTIMAL POWER FLOW APIS

Two-terminal dc Lines

Power Technologies, Inc.

3.20 Two-terminal dc Lines

The following API is used to modify two-terminal dc line constraint records within the PSS/E
working file. The API is invoked through the subroutine call:
OPF_2TERMDC_API(IDC, REALAR, IERR, NERR)

or may be issued as the following batch command:

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, invalid two-terminal dc line specified.
IERR = -1, non-fatal error occurred. Possible warning messages are:
dc maximum flow limit is less than the minimum.
dc maximum voltage limit is less than the minimum

Integer NERR

The number of lines stored in the message buffer.

3-54

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

OPTIMAL POWER FLOW APIS

Write OPF Data File (RWOPNW)

Power Technologies, Inc.

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)

or is issued as the following batch command:

BAT_RWOP
OUT OFILE

SID

ALL

STATUS(1)

STATUS(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.

Integer ALL

Is the "all" buses or selected buses subsystem flag.

ALL = 1, process all buses.
ALL = 0, process only selected buses.

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(1), omit isolated buses.
STATUS(2), omit out-of-service branches.
STATUS(3), include subsystem data.
STATUS(4), include subsystem tie lines.

Integer OUT

Is the output option selection.

OUT = 0, output to a data file specified by OFILE.
OUT = 1, output to the progress window.

Character OFILE*260 Is the output filename.

Integer IERR

PSS/E-29

Is the error return.

IERR = 0, no error.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.
IERR = 3, OUT is in error.
IERR = 4, unable to open OFILE.
IERR = 5, no OPF data in the case.

GUIDE TO PSS/E BATCH COMMANDS

3-55

This page intentionally left blank.

3-56

GUIDE TO PSS/E BATCH COMMANDS

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

Is the "all" buses or selected subsystem flag.

ALL = 1, process all buses.
ALL = 0, process only selected buses.

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

GUIDE TO PSS/E BATCH COMMANDS

4-1

DYNAMICS SIMULATION APIS

CHSBNW

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, either ALL or SID is in error.
IERR = 2, bad starting channel, VAR or ICON index.
IERR = 3, STATUS(4) is in error.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

DYNAMICS SIMULATION APIS

CHSBNW

IERR = 4, STATUS(5) is in error.

IERR = 5, STATUS(6) is in error.
IERR = 6, reached end of ICON, VAR, or channel array.
IERR = 7, angle statistics already in channels.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

4-3

DYNAMICS SIMULATION APIS

DOCUNW

Power Technologies, Inc.

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

Is a valid bus subsystem ID. Valid subsystem IDs range from 0 to 3. A bus
subsystem must have been previously defined.

Integer ALL

Is the "all" buses or selected buses subsystem flag.

ALL = 1, process all buses.
ALL = 0, process only selected buses.

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

Is the error return.

IERR = 0, no error.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

DYNAMICS SIMULATION APIS

DYDANW

Power Technologies, Inc.

4.3 DYDANW
This API is used to write out dynamics model data in the form of a Dynamics Data Input file. The
API is invoked by the use of the statement:
DYDANW(SID, ALL, STATUS, OUT, OFILE, IERR)

or:
BAT_DYDA

SID

ALL

STATUS(1)

STATUS(2)

STATUS(3)

OUT

OFILE

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

Is the "all" buses or selected buses subsystem flag.

ALL = 1, process all buses.
ALL = 0, process only selected buses.

Integer STATUS(3)

Is a three-element array.
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

Is the output option selection.

OUT = 0, output to a data file specified by OFILE.
OUT = 1, output to the progress window.

GUIDE TO PSS/E BATCH COMMANDS

4-5

DYNAMICS SIMULATION APIS

DYDANW

Power Technologies, Inc.

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

Integer IERR

4-6

Is the error return.

IERR = 0, no error.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.
IERR = 3, OUT is in error.
IERR = 4, error opening OFILE.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

DYNAMICS SIMULATION APIS

RSTRNW

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error.
IERR = 1, error opening SFILE.
IERR = 2, error reading from SFILE.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

4-7

DYNAMICS SIMULATION APIS

SNAPNW

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, STATUS is in error.
IERR = 2, error opening SFILE.
IERR = 3, error writing to SFILE.

4-8

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

DYNAMICS SIMULATION APIS

LDLIST

Power Technologies, Inc.

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

Is a valid bus subsystem ID. Valid subsystem IDs range from 0 to 3. A bus
subsystem must have been previously defined.

Integer ALL

Is the "all" buses or selected buses subsystem flag.

ALL = 1, process all buses.
ALL = 0, process only selected buses.

Integer STATUS(2)

Is a two-element array.
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

Is the error return.

IERR = 0, no error.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.

GUIDE TO PSS/E BATCH COMMANDS

4-9

DYNAMICS SIMULATION APIS

LDMOD_STATUS

Power Technologies, Inc.

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
API is invoked by the use of the statement:
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

Is the error return.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

DYNAMICS SIMULATION APIS

LDMOD_STATUS2

Power Technologies, Inc.

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
use of the statement:
LDMOD_STATUS2(IBUS, LDID, LTYPE, IST, IERR)

or:
BAT_LDMOD_STATUS2 IBUS

LDID

LTYPE IST

where:
Integer IBUS

Is the external bus number.

Character LDID *2

Is the two-character load 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

Is the error return.

IERR = 0, no error.
IERR = 1, load or model not found.
IERR = 2, invalid LTYPE.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

4-11

DYNAMICS SIMULATION APIS

LDMOD_REMOVE

Power Technologies, Inc.

4.9 LDMOD_REMOVE
This API is used to remove a load model from dynamics working memory. The API is invoked by
the use of the statement:
LDMOD_REMOVE(MTYPE, IBUS, LMODID, LTYPE, IERR)

or:
BAT_LDMOD_REMOVE

MTYPE

IBUS

LMODID

LTYPE

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 IERR

Is the error return.

IERR = 0, no error.
IERR = 1, model not found.
IERR = 2, invalid LTYPE.
IERR = 3, invalid MTYPE.
IERR = 4, invalid IBUS.

4-12

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

DYNAMICS SIMULATION APIS

LDMOD_UNCONNECTED

Power Technologies, Inc.

4.10 LDMOD_UNCONNECTED
This API is used to list or remove unconnected load models from dynamics working memory. The
API is invoked by the use of the statement:
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

Is the error return.

IERR = 0, no error.
IERR = 1, invalid OPT.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

4-13

DYNAMICS SIMULATION APIS

LDMOD_PACK

Power Technologies, Inc.

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
invoked by the use of the statement:
LDMOD_PACK

or:
BAT_LDMOD_PACK

4-14

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

DYNAMICS SIMULATION APIS

LDMOD_USER

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error.
IERR = 1, invalid OPT.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

4-15

DYNAMICS SIMULATION APIS

CHANGE_LDMOD_DATA

Power Technologies, Inc.

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

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 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 LTYPE

Is the load model type.

LTYPE = 1, load characteristic model.
LTYPE = 2, load relay model.

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

Is the error return.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

DYNAMICS SIMULATION APIS

ADD_LOAD_MODEL

Power Technologies, Inc.

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

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 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 LTYPE

Is the load model type.

LTYPE = 1, load characteristic model.
LTYPE = 2, load relay model.

Character MDNAME*6

Is the six-character model name.

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

GUIDE TO PSS/E BATCH COMMANDS

4-17

DYNAMICS SIMULATION APIS

ADD_LOAD_MODEL

Integer IERR

4-18

Power Technologies, Inc.

Is the error return.

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 = 5, invalid model name.
IERR = 6, model name and model type do not match CONs.
IERR = 7, invalid number of CONs or ICONs.
IERR = 8, data arrays full.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

DYNAMICS SIMULATION APIS

MLSTNW

Power Technologies, Inc.

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

Is the "all" buses or selected buses subsystem flag.

ALL = 1, process all buses.
ALL = 0, process only selected buses.

Integer STATUS(3)

Is a three-element array.
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

Is the error return.

IERR = 0, no error.
IERR = 1, either ALL or SID is in error.
IERR = 2, STATUS is in error.

GUIDE TO PSS/E BATCH COMMANDS

4-19

DYNAMICS SIMULATION APIS

CHANGE_PLMOD_DATA

Power Technologies, Inc.

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

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

4-20

Is the error code.

IERR = 0, no error.
IERR = 1, machine not found.
IERR = 2, invalid model type.
IERR = 3, invalid model name.
IERR = 4, model not found.
IERR = 5, invalid CON or ICON position.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

DYNAMICS SIMULATION APIS

ADD_PLANT_MODEL

Power Technologies, Inc.

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

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

Is the six-character model name.

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

Is the number of ICONs in the model.

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

Is the number of CONs in the model.

Integer DATA(NCON)

Are the CON data.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

4-21

DYNAMICS SIMULATION APIS

ADD_PLANT_MODEL

Integer IERR

4-22

Power Technologies, Inc.

Is the error return.

IERR = 0, no error.
IERR = 1, machine not found.
IERR = 2, plant model tables full.
IERR = 3, plant model tables corrupted.
IERR = 4, invalid model type.
IERR = 5, invalid model name.
IERR = 6, model name and type dont match.
IERR = 7, invalid number of ICONs or CONs.
IERR = 8, data arrays full.
IERR = 9, invalid specification of second machine.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

DYNAMICS SIMULATION APIS

PLMOD_STATUS

Power Technologies, Inc.

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

Is the external plant bus number.

Character ID*2

Is the two-character machine 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.

Integer IST

Is the new model status.

IST = 0, model out of service.
IST = 1, model in service.

Integer IERR

Is the error return.

IERR = 0, no error.
IERR = 1, machine not found.
IERR = 2, invalid model type.
IERR = 3, model not found.
IERR = 4, invalid status.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

4-23

DYNAMICS SIMULATION APIS

PLMOD_REMOVE

Power Technologies, Inc.

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

Is the external plant bus number.

Character ID*2

Is the two-character machine 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.

Integer IERR

Is the error code.

IERR = 0, no error.
IERR = 1, machine not found.
IERR = 2, invalid model type.
IERR = 3, model not found.

4-24

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

DYNAMICS SIMULATION APIS

PLMOD_UNCONNECTED

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error.
IERR = 1, invalid OPT.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

4-25

DYNAMICS SIMULATION APIS

PLMOD_PACK

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

DYNAMICS SIMULATION APIS

PLMOD_USER

Power Technologies, Inc.

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.
IERR = 1, invalid OPT.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

4-27

DYNAMICS SIMULATION APIS

PLMOD_CONSISTENCY

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

DYNAMICS SIMULATION APIS

RLLIST

Power Technologies, Inc.

4.24 RLLIST
This API is used to list line related models in the dynamics working arrays. The API is invoked by
use of the statement:
RLLIST(SID, ALL, STATUS, IERR)

or:
BAT_RLLIST SID ALL STATUS(1) STATUS(2)

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

Is the "all" buses or selected buses subsystem flag.

ALL = 1, process all buses.
ALL = 0, process only selected buses.

Integer STATUS(2)

Is a two-element array.
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.
IERR = 2, STATUS is in error.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

4-29

DYNAMICS SIMULATION APIS

CHANGE_RLMOD_DATA

Power Technologies, Inc.

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

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 ICON, this
value should be set to either $$ or .
Integer IERR

4-30

Is the error code.

IERR = 0, no error.
IERR = 1, branch not found.
IERR = 2, invalid relay slot.
IERR = 3, invalid model name.
IERR = 4, model not found.
IERR = 5, invalid CON or ICON.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

DYNAMICS SIMULATION APIS

ADD_RELAY_MODEL

Power Technologies, Inc.

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

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

Is the six-character model name.

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.

Integer IERR

Is the error code.

IERR = 0, no error.
IERR = 1, branch not found.
IERR = 2, invalid relay slot.
IERR = 3, line relay tables full.
IERR = 4, invalid model name.
IERR = 5, invalid number of CONs or ICONs.
IERR = 6, data arrays full.
IERR = 7, tables corrupted.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

4-31

DYNAMICS SIMULATION APIS

RLMOD_STATUS

Power Technologies, Inc.

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

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.

Integer IST

Is the new desired status.

IST = 0, out of service.
IST = 1, in service.

Integer IERR

Is the error code.

IERR = 0, no error.
IERR = 1, branch not found.
IERR = 2, invalid relay slot.
IERR = 3, model not found.
IERR = 4, invalid status.

4-32

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

DYNAMICS SIMULATION APIS

RLMOD_REMOVE

Power Technologies, Inc.

4.28 RLMOD_REMOVE
This API is used to remove a line relay model from the dynamics working memory. The API is
invoked by use of the statement:
RLMOD_REMOVE(IBUS, JBUS, ID, RS, IERR)

or:
BAT_RLMOD_REMOVE IBUS JBUS ID RS

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.

Integer IERR

Is the error code.

IERR = 0, no error.
IERR = 1, branch or relay not found.
IERR = 2, invalid relay slot.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

4-33

DYNAMICS SIMULATION APIS

RLMOD_UNCONNECTED

Power Technologies, Inc.

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.
IERR = 1, invalid OPT.

4-34

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

Power Technologies, Inc.

DYNAMICS SIMULATION APIS

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

GUIDE TO PSS/E BATCH COMMANDS

4-35

DYNAMICS SIMULATION APIS

RLMOD_USER

Power Technologies, Inc.

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.
IERR = 1, invalid OPT.

4-36

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

DYNAMICS SIMULATION APIS

SET_NETFRQ

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

4-37

DYNAMICS SIMULATION APIS

SET_OSSCAN

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

DYNAMICS SIMULATION APIS

SET_RELANG

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

4-39

DYNAMICS SIMULATION APIS

SET_RELSCN

Power Technologies, Inc.

4.35 SET_RELSCN
This API is used to set or obtain the settings of a generic relay scanning function. The API is
invoked by use of the statement:
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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

DYNAMICS SIMULATION APIS

SET_VLTSCN

Power Technologies, Inc.

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

GUIDE TO PSS/E BATCH COMMANDS

4-41

This page intentionally left blank.

4-42

GUIDE TO PSS/E BATCH COMMANDS

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
invoked by the use of the statement:
SBSINIT

or:
BAT_SBSINIT

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

5-1

SUBSYSTEM DEFINITION APIS

Area Subsystem Definition APIs

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, SID is not valid.

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
API is invoked by the use of the statement:
SBSASET(SID, NUM, AREAS, IERR)

or:
BAT_ASYS

SID

NUM

AREAS(1) AREAS(NUM)

where:
Integer SID

Is a valid area subsystem ID. Valid area subsystem IDs range from 0 to 3.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, SID is not valid.

5-2

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

SUBSYSTEM DEFINITION APIS

Area Subsystem Definition APIs

Power Technologies, Inc.

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

Is a valid area subsystem ID. Valid area subsystem IDs range from 0 to 3.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, SID is not valid.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

5-3

SUBSYSTEM DEFINITION APIS

Bus Subsystem Definition APIs

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, SID is not valid.

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
API is invoked by the use of the statement:
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

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.

Integer USEKV

USEKV = 0, do not use BASEKV values.

USEKV = 1, use BASEKV values.

Real BASEKV(2)

Is an array of two elements.

BASEKV(1) is the minimum basekV limit.
BASEKV(2) is the maximum basekV limit.

Integer NUMAREA

Is the number of areas to set.

5-4

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

SUBSYSTEM DEFINITION APIS

Bus Subsystem Definition APIs

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, SID is not valid.

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

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.

Integer USEKV

USEKV = 0, do not use BASEKV values.

USEKV = 1, use BASEKV values.

Real BASEKV(2)

Is an array of two elements.

BASEKV(1) is the minimum basekV limit.
BASEKV(2) is the maximum basekV limit.

Integer NUMAREA

Is the number of areas to set.

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

GUIDE TO PSS/E BATCH COMMANDS

5-5

SUBSYSTEM DEFINITION APIS

Bus Subsystem Definition APIs

Integer BUSLEN

Power Technologies, Inc.

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

Is the number of zones to set.

Integer ZONES

Is an array of NUMZONE elements that contains the zones to set.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, SID is not valid.

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

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, SID is not valid.

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

Is the error return.

IERR = 0, no error occurred.

5-6

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

SUBSYSTEM DEFINITION APIS

Bus Subsystem Definition APIs

Power Technologies, Inc.

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
API is invoked by the use of the statement:
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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, SID is not valid.
IERR = 2, error opening SFILE.

5.3.7 SBSBSRCL
This API is used to "recall" a selected bus subsystem saved in a bus subsystem file. The API is
invoked by the use of the statement:
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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, SID is not valid.
IERR = 2, error opening SFILE.
IERR = 3, not a valid bus subsystem file
IERR = 4, items in bus subsystem file not found in working case

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

5-7

SUBSYSTEM DEFINITION APIS

Owner Subsystem Definition APIs

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, SID is not valid.

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

Is a valid owner subsystem ID. Valid owner subsystem IDs range from
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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, SID is not valid.

5-8

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

SUBSYSTEM DEFINITION APIS

Owner Subsystem Definition APIs

Power Technologies, Inc.

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

Is a valid owner subsystem ID. Valid owner subsystem IDs range from
0 to 3.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, SID is not valid.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

5-9

SUBSYSTEM DEFINITION APIS

Zone Subsystem Definition APIs

Power Technologies, Inc.

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

Is the error return.

IERR = 0, no error occurred.
IERR = 1, SID is not valid.

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.
The API is invoked by the use of the statement:
SBSZSET(SID, NUM, ZONES, IERR)

or:
BAT_ZSYS

SID

NUM

ZONES(1) ZONES(NUM)

where:
Integer SID

Is a valid zone subsystem ID. Valid zone subsystem IDs range from 0 to 3.

Integer NUM

Is the number of zones to set.

Integer ZONES

Is an array of NUM elements that contains the zones to set.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, SID is not valid.

5-10

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

SUBSYSTEM DEFINITION APIS

Zone Subsystem Definition APIs

Power Technologies, Inc.

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

Is a valid zone subsystem ID. Valid zone subsystem IDs range from 0 to 3.

Integer IERR

Is the error return.

IERR = 0, no error occurred.
IERR = 1, SID is not valid.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

5-11

This page intentionally left blank.

5-12

GUIDE TO PSS/E BATCH COMMANDS

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

GUIDE TO PSS/E BATCH COMMANDS

6-1

SUBSYSTEM SELECTION APIS

Area Subsystem Selection APIs

Power Technologies, Inc.

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

Is a valid area subsystem ID. Valid area subsystem IDs range from 0 to 3.

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

Is a valid area subsystem ID. Valid area subsystem IDs range from 0 to 3.
An area subsystem must have been previously defined.

Integer ALL

Is the all areas or selected subsystem flag.

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

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

Is a valid area subsystem ID. Valid area subsystem IDs range from 0 to 3.
An area subsystem must have been previously defined.

Integer AREA

Is returned as an area number.

AREA > 0, area number.
AREA = 0, all valid selected areas have been returned.

6-2

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

SUBSYSTEM SELECTION APIS

Area Subsystem Selection APIs

Power Technologies, Inc.

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.
The API is invoked by the use of the statement:
SBSALTERM(SID)

where:
Integer SID

Is a valid area subsystem ID. Valid area subsystem IDs range from 0 to 3.
An area subsystem must have been previously defined.

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

Is a valid area subsystem ID. Valid area subsystem IDs range from 0 to 3.

Integer AREA

Is the area to test.

Logical EXIST

Is returned as the existence flag.

EXIST = .FALSE., area is not selected in the area subsystem.
EXIST = .TRUE., area is selected in the area subsystem.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

6-3

SUBSYSTEM SELECTION APIS

Bus Subsystem Selection APIs

Power Technologies, Inc.

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

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.

Logical INIT

Is returned as the existence flag.

INIT = .FALSE., bus subsystem has not been defined.
INIT = .TRUE., bus subsystem has been defined.

6-4

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

SUBSYSTEM SELECTION APIS

Bus Subsystem Selection APIs

Power Technologies, Inc.

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

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.
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

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.
A bus subsystem must have been previously defined.

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

GUIDE TO PSS/E BATCH COMMANDS

6-5

SUBSYSTEM SELECTION APIS

Bus Subsystem Selection APIs

Power Technologies, Inc.

where:
Integer SID

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.
A bus subsystem must have been previously defined.

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, ZONE, OWNER contain valid selections.
FLAG = 0, all valid selections have been returned.

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
invoked by the use of the statement:
SBSBLOWNERNB(SID, OWNER, FLAG)

where:
Integer SID

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.
A bus subsystem must have been previously defined.

Integer OWNER

Is returned as the current selected owner number.

Integer FLAG

Is returned as status flag.

FLAG > 0, OWNER contain valid selection.
FLAG = 0, all valid selections have been returned.

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
subsystem selector. The API is invoked by the use of the statement:
SBSVLAREA(SID, AREA, EXIST)

where:
Integer SID

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.

Integer AREA

Is the area to test.

Logical EXIST

Is returned as the existence flag.

EXIST = .FALSE., area is not selected in the bus subsystem.
EXIST = .TRUE., area is selected in the bus subsystem.

6-6

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

SUBSYSTEM SELECTION APIS

Bus Subsystem Selection APIs

Power Technologies, Inc.

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

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.

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

Is returned as the existence flag.

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

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.

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

GUIDE TO PSS/E BATCH COMMANDS

6-7

SUBSYSTEM SELECTION APIS

Bus Subsystem Selection APIs

Power Technologies, Inc.

Logical EXIST

Is returned as the existence flag.

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

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.

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

Is returned as the existence flag.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

SUBSYSTEM SELECTION APIS

Bus Subsystem Selection APIs

Power Technologies, Inc.

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

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.

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

Is returned as the existence flag.

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
subsystem selector. The API is invoked by the use of the statement:
SBSVLOWNER(SID, OWNER, EXIST)

where:
Integer SID

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.

Integer OWNER

Is the owner to test.

Logical EXIST

Is returned as the existence flag.

EXIST = .FALSE., owner is not selected in the bus subsystem.
EXIST = .TRUE., owner is selected in the bus subsystem.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

6-9

SUBSYSTEM SELECTION APIS

Bus Subsystem Selection APIs

Power Technologies, Inc.

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
subsystem selector. The API is invoked by the use of the statement:
SBSVLZONE(SID, ZONE, EXIST)

where:
Integer SID

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.

Integer ZONE

Is the zone to test.

Logical EXIST

Is returned as the existence flag.

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
use of the statement:
SBSBLAINIT(SID, ALL, BYAREA, BYBUS, BYKV, BYOWNR, BYZONE)

where:
Integer SID

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.
A bus subsystem must have been previously defined.

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

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

SUBSYSTEM SELECTION APIS

Bus Subsystem Selection APIs

Power Technologies, Inc.

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

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.
A bus subsystem must have been previously defined.

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.
ALL = 0, process only selected buses.

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

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.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

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.
A bus subsystem must have been previously defined.

Integer AREA

Is returned as the current area number for the bus sequence number.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

6-11

SUBSYSTEM SELECTION APIS

Bus Subsystem Selection APIs

Power Technologies, Inc.

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
This API is used to loop through all selected buses and return bus sequence numbers in reports that
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

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.
A bus subsystem must have been previously defined.

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.17 SBSBLZONE
This API is used to loop through all selected buses and return bus sequence numbers in reports that
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

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.
A bus subsystem must have been previously defined.

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-12

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

SUBSYSTEM SELECTION APIS

Bus Subsystem Selection APIs

Power Technologies, Inc.

6.2.18 SBSBLOWNER
This API is used to loop through all selected buses and return bus sequence numbers in reports that
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

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.
A bus subsystem must have been previously defined.

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.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

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.
A bus subsystem must have been previously defined.

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

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.
A bus subsystem must have been previously defined.

Real KVMIN

Is returned as the selected base kV minimum.

Real KVMAX

Is returned as the selected base kV maximum.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

6-13

SUBSYSTEM SELECTION APIS

Bus Subsystem Selection APIs

Power Technologies, Inc.

6.2.21 SBSGTFLG
This API is used to return the flags indicating how buses have been selected. The API is invoked
by the use of the statement:
SBSGTFLG(SID, ALL, BYAREA, BYBUS, BYKV, BYOWNR, BYZONE)

where:
Integer SID

Is a valid bus subsystem ID. Valid bus subsystem IDs range from 0 to 3.
A bus subsystem must have been previously defined.

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

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-14

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

SUBSYSTEM SELECTION APIS

Owner Subsystem Selection APIs

Power Technologies, Inc.

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
use of the statement:
SBSZDEF(SID, INIT)

where:
Integer SID

Is a valid owner subsystem ID. Valid owner subsystem IDs range from
0 to 3.

Logical INIT

Is returned as the existence flag.

INIT = .FALSE., owner subsystem has not been defined.
INIT = .TRUE., owner subsystem has been defined.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

6-15

SUBSYSTEM SELECTION APIS

Owner Subsystem Selection APIs

Power Technologies, Inc.

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

Is a valid owner subsystem ID. Valid owner subsystem IDs range from
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

Is the value to initialize the system at. Normally initialized with a value of 0.

6.3.3 SBSOLOWNER
This API is used to loop through all selected owners. SBSOLINIT must have been called previously
to initialize the looping. The API is invoked by the use of the statement:
SBSOLOWNERS(SID, OWNER)

where:
Integer SID

Is a valid owner subsystem ID. Valid owner subsystem IDs range from
0 to 3. A owner subsystem must have been previously defined.

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

Is a valid owner subsystem ID. Valid owner subsystem IDs range from
0 to 3. A owner subsystem must have been previously defined.

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

SUBSYSTEM SELECTION APIS

Owner Subsystem Selection APIs

Power Technologies, Inc.

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

Is a valid owner subsystem ID. Valid owner subsystem IDs range from
0 to 3.

Integer OWNER

Is the owner to test.

Logical EXIST

Is returned as the existence flag.

EXIST = .FALSE., owner is not selected in the owner subsystem.
EXIST = .TRUE., owner is selected in the owner subsystem.

PSS/E-29

GUIDE TO PSS/E BATCH COMMANDS

6-17

SUBSYSTEM SELECTION APIS

Zone Subsystem Selection APIs

Power Technologies, Inc.

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

Is a valid zone subsystem ID. Valid zone subsystem IDs range from 0 to 3.

Logical INIT

Is returned as the existence flag.

INIT = .FALSE., zone subsystem has not been defined.
INIT = .TRUE., zone subsystem has been defined.

6-18

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

SUBSYSTEM SELECTION APIS

Zone Subsystem Selection APIs

Power Technologies, Inc.

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

Is a valid zone subsystem ID. Valid zone subsystem IDs range from 0 to 3.
A zone subsystem must have been previously defined.

Integer ALL

Is the all zones or selected subsystem flag.

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

Integer INIT

Is the value to initialize the system at. Normally initialized with a value of 0.

6.4.3 SBSZLZONE
This API is used to loop through all selected zones. SBSZLINIT must have been called previously
to initialize the looping. The API is invoked by the use of the statement:
SBSZLZONE(SID, ZONE)

where:
Integer SID

Is a valid zone subsystem ID. Valid zone subsystem IDs range from 0 to 3.
A zone subsystem must have been previously defined.

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
API is invoked by the use of the statement:
SBSZLTERM(SID)

where:
Integer SID

PSS/E-29

Is a valid zone subsystem ID. Valid zone subsystem IDs range from 0 to 3.
A zone subsystem must have been previously defined.

GUIDE TO PSS/E BATCH COMMANDS

6-19

SUBSYSTEM SELECTION APIS

Zone Subsystem Selection APIs

Power Technologies, Inc.

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
subsystem selector. The API is invoked by the use of the statement:
SBSZVLZ(SID, ZONE, EXIST)

where:
Integer SID

Is a valid zone subsystem ID. Valid zone subsystem IDs range from 0 to 3.

Integer ZONE

Is the zone to test.

Logical EXIST

Is returned as the existence flag.

EXIST = .FALSE., zone is not selected in the zone subsystem.
EXIST = .TRUE., zone is selected in the zone subsystem.

6-20

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29

SUBSYSTEM SELECTION APIS

Miscellaneous Subsystem APIs

Power Technologies, Inc.

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
invoked by the use of the statement:
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
the use of the statement:
SBSRBDBL(SID)

where:
Integer SID

Is a valid subsystem ID. Valid subsystem IDs range from 0 to 3.

6.5.3 SBSRBDOL
This API is used to refresh the owner displays in the owner and bus subsystem selectors. The API
is invoked by the use of the statement:
SBSRBDOL(SID)

where:
Integer SID

Is a valid subsystem ID. Valid subsystem IDs range from 0 to 3.

6.5.4 SBSRBDZL
This API is used to refresh the zone displays in the zone and bus subsystem selectors. The API is
invoked by the use of the statement:
SBSRBDZL(SID)

where:
Integer SID

PSS/E-29

Is a valid subsystem ID. Valid subsystem IDs range from 0 to 3.

GUIDE TO PSS/E BATCH COMMANDS

6-21

This page intentionally left blank.

6-22

GUIDE TO PSS/E BATCH COMMANDS

PSS/E-29