Using FCPUTIL
About FCPUTIL
FCPUTIL is a FirstClass Protocol utility designed to check the status of the server and perform some commands related to maintaining the server. It requires an account with "Monitor server" and "Maintain server" privileges, and it can be used across a network.
Advantages
There are some major advantages of using FCPUTIL over other options such as NET Pause or fcsctl pause:
- FCPUTIL can return the status of an action. Therefore a script can be constructed to deal with the returned status.
- It supports considerably more functions than the NET command's STOP, PAUSE, and CONTINUE.
- It is both network-based and platform-independent, so it can be run from a different machine than the one hosting the server, and even a different platform.
Differences between FCPUTIL and FCUTIL
FCUTIL was originally a very simple Windows-specific utility. FCPUTIL has since grown to replace (and surpass) this historical tool. FCPUTIL provides much of the same feature set as FCUTIL, with the following major differences:
- FCUTIL must be run on the same machine as the FirstClass server, while FCPUTIL can be run across a network.
- FCUTIL requires a Windows-specific platform, while FCPUTIL does not require a matching platform.
For example, the Windows version of FCPUTIL could be used to maintain Windows or OS X servers, or vice versa.
- FCPUTIL includes a GETSTATS command that FCUTIL does not.
GETSTATS fetches the current values of real-time counters maintained by the server, such as the number of active sessions, task load, the number of open files, etc. Many of the stats available on the server monitor are available remotely through this command.
- FCPUTIL does not support the Internet Services-specific and Voice Services-specific features of FCUTIL.
- Since FCPUTIL uses a real client login session, it requires connection and account information and therefore requires a standard settings file (fcputil.fc).
- FCUTIL directly returns subsystem error return codes, while FCPUTIL returns high-level (client) error codes. For example, a CONTINUE command issued when no mirrors are paused will return a 4117 error through FCUTIL, but a 1030 through FCPUTIL. Both are "access denied" errors.
Setting up FCPUTIL
FCPUTIL is installed automatically with the FirstClass Server, so all you need to do is set it up, which can be done in three steps:
[Link]STEP 1: Create a user account
STEP 1: Create a user account
 NoteYou do not need to set up a new account, but we recommend that you do, since the common alternative would be to use the admin account. If you choose not to set up a new account, make sure the account you use has the "Monitor server" and "Maintain server" privileges.
1 Create a new user and give the new account a strong password.
2 Give it two additional privileges: "Monitor server" and "Maintain server".
3 Make sure this account is a member of a group which has the ability to save passwords.
Note
This account does not need to be a subadmin account.
STEP 2: Create a settings file
1 Go to the folder where your FirstClass executable files exist.
2 Make a copy of a settings file such as Inetsvcs.fc, and rename the copy to fcputil.fc.
STEP 3: Customize the account
1 Launch the FirstClass client.
2 Click Browse.
3 Find the folder where FirstClass is installed, and open the fcputil.fc settings file.
Note
The fcputil.fc file must be stored in the same location as the FirstClass executable files.
4 Enter the user id and password for the account and click Save.
5 Log in with the FirstClass client to make sure that the client can connect to a server using this settings file.
Common errors
The two most common errors when setting up FCPUTIL are:
1003 |
Username or password is incorrect. Also, make sure the account has the appropriate permissions (Monitor server and Maintain server). |
4105 |
fcputil.fc is not in the same location as FCPUTIL, or the account is not set up properly. Review the steps above. |
Syntax
The command line syntax for FCPUTIL is similar to the FCUTIL tool mentioned above. Simply run FCPUTIL with the command to process and any additional arguments specific to that command.
Usage: fcputil <cmd> [parameter] [SERVER || FCS || IS || FCINTSRV || VS || VSERVICE]
or: fcputil [-s|-S] getstats [id [id ...] ]
or: fcputil -h - gives the basic syntax help plus common commands
or: fcputil -H - gives syntax with a full list of command keywords
Switch |
Parameters |
Meaning |
-h |
|
displays command help for the most commonly used operations |
-H |
|
displays complete list of all commands available |
-v |
|
displays FCPUTIL version |
-s |
|
|
-S |
|
|
Command |
Parameters |
Meaning |
Common Core Commands |
ABOUT |
|
displays the server version (in the server console log file) |
WAIT |
n |
pauses fcputil for the specified number of seconds, where n represents number of seconds. Note This command is local-only. This means it does not communicate with the server end and therefore does not require a settings file to use it. |
BROADCAST |
"<message>" |
send a broadcast to all users logged in |
DISABLE |
|
disables all logins (except for admin/subadmin/maintenance users) |
ENABLE |
|
enables logins by all users and services |
LOGOFF |
<userid> |
forces logoff of the specified user |
AUDIT |
|
starts an audit on the core server |
TC |
|
an alias for the AUDIT command above |
TRASH |
|
an alias for the AUDIT command above |
STOPAUDIT |
|
force the audit to stop (after the audit of the current folder completes) |
FAST |
|
performs a fast (normal) shutdown |
POLITE |
|
performs a polite shutdown |
QUIT |
|
tells the server to terminate/exit (for the server, this is the same as FAST ) |
Backups, Mirroring, Snapshot Hold |
HOLD |
n |
puts the server into "snapshot hold", a paused state for the specified number of seconds, where n represents the number of seconds |
PAUSE |
|
pauses the mirror until CONTINUE command is issued; returns 0 if successful, FirstClass error code if unsuccessful |
CONTINUE |
|
releases the mirror from the paused state triggered by PAUSE; returns 0 if successful, FirstClass error code if unsuccessful |
CONT |
|
an alias for CONTINUE above |
RESYNC |
|
forces a full mirror resync of all mirrors; returns 0 if successful, FirstClass error code if unsuccessful |
MCHECK |
|
returns the current state of the mirror as an error level-compatible return code: 0: All mirrors are paused. 1: No volumes are mirrored. 2:
All mirrors are synchronized and active. 3: At least one mirrored volume is still synchronizing. 4: Mirror status varies depending on the mirrored volume. 5: At least one mirror has failed. |
MDUMP |
|
returns the current state of the mirror (see MCHECK) and dumps the current status as text in the console/log file |
MIRRORLOG |
|
toggles the display of mirroring-related debug messages to the console/log file |
QSHOW |
|
displays a detailed list of the mirroring queue  Warning Output may be extremely large. |
QSUMMARY |
|
displays a summary of the mirroring queue |
Performance and Statistics |
GETSTATS |
|
|
PSTATS |
|
dumps a summary of performance-related statistics to the console/log file |
PRESET |
|
resets the performance statistics reported in the PSTATS command |
MEM |
|
displays a summary of memory use in the server console/log file |
Other Core Commands |
GATEWAY |
<gateway-name> |
force a gateway to connect (aliases are REPLICATE and NOW) |
REPLICATE |
<gateway-name> |
an alias for the GATEWAY or NOW commands, forces the specified gateway to connect |
NOW |
<gateway-name> |
an alias for the GATEWAY or REPLICATE commands, forces the specified gateway to connect |
HIGH |
|
set the internal server priority to high |
MEDIUM |
|
set the internal server priority to medium |
MED |
|
an alias for the MEDIUM command above |
LOW |
|
set the internal server priority to low |
Other Current Status Commands |
GATEWAYS |
|
dumps a list of gateways to the console/log file |
GROUPS |
|
dumps a list of groups to the console/log file |
LISTFILES |
|
dumps a list of all open files to the console/log file Warning Dangerous, as large sites have tens of thousands of these. |
LISTOBJS |
|
dumps a list of all open objects to the console/log file Warning Dangerous, as large sites have many of these. |
NOTIFY |
|
dumps the notify table to the console/log file |
SESSION |
|
displays the status of sessions to the console/log file |
SESSIONS |
|
an alias for the SESSION command above |
STATS |
|
displays some server summary statistics |
STATUS |
|
another (different) status summary of sessions |
TASKS |
|
dumps a list of server tasks to the console / log file |
Common Logging Options |
CONSOLE |
|
toggles the console to file option, which in modern servers means turn fcs.log file logging on or off |
CONSOLELOG |
|
forces the console log to be enabled (not a toggle) |
NOCONSOLELOG |
|
forces the console log to be disabled (not a toggle) |
LOGINLOG |
|
toggle the reporting of all logins and logoffs to the console/log file |
MAILLOG |
|
toggles message (MTA) delivery logging |
MAIL |
|
an alias of the MAILLOG command above |
Other Logging and Debugging Options |
BATCHADMIN |
|
enables server logging for FC script (batch admin) operations |
REMADMIN |
|
an alias for the BATCHADMIN command above |
DB |
|
toggles database extension logging on/off |
DBGALL |
|
enables full server debug logging |
DEBUG |
|
an alias for the DBGALL command above |
DBGCORE |
|
enables server debug logging for core server operations |
DBGDIR |
|
enables server debug logging for user directory operations |
DBGFILE |
|
enables server debug logging for file I/O operations (mostly core buffering messages) |
DBGIS |
|
enables server debug logging for services (such as IS) |
DBGTC |
|
enables server debug logging for audit operations |
DBGNONE |
|
disables all server debug logging |
DBGSESS |
|
enables server debug logging for session-related operations |
GWCDATA |
|
toggles reporting of gateway client protocol debugging - data dumps |
GWCDEBUG |
|
enables full (verbose) reporting of gateway client protocol |
GWCNONE |
|
disables reporting of gateway client protocol debug messages |
GWCOPEN |
|
enables gateway client protocol debugging - opens and closes |
GWCWARN |
|
enables gateway client protocol debugging - warning messages |
GWMAIL |
|
enables gateway client protocol debugging - mail-related operations |
PACKET |
|
enables full packet debugging logging, including packet data contents |
PKTCONN |
|
enables connection-related packet debugging messages to the console/log file |
PKTERR |
|
enables packet error debugging messages to the console/log file |
PKTMDM |
|
enables modem-related (session-related) packet debugging messages to the console/log file |
PKTMOST |
|
enables all packet debugging messages except send/received packet data to the console/log file |
PKTNONE |
|
disables all packet debugging messages |
PKTSTAT |
|
dumps several packet-related statistics to the console/log file |
PKTRX |
|
enables the dumping of received packets debugging messages to the console/log file |
PKTTX |
|
enables the dumping of sent packets debugging messages to the console/log file |
RESET |
|
resets the modems and network dispatchers (no longer supported by servers) |
Example
This script incorporates multiple FCPUTIL commands. It warns users that a shutdown is imminent, and then performs a fast shutdown.
FCPUTIL BROADCAST "Server shutdown in 5 minutes."
FCPUTIL WAIT 240
FCPUTIL BROADCAST "Server shutdown in 1 minute. Please log off."
FCPUTIL WAIT 60
FCPUTIL BROADCAST "Server shutting down now."
FCPUTIL WAIT 5
FCPUTIL FAST
This is the output to the console log file that resulted from two MDUMP commands. One was issued while the mirror was still synchronizing, and the other was issued after synchronization was complete:
[2010/03/01 01:32:04] Volume 8001 ("G:") mirror state is FULL SYNC (90%).
[2010/03/01 01:32:04] Volume 853C ("E:") mirror is ACTIVE.
[2010/03/01 01:32:54] Mirror: Beginning incremental sync of 13 item(s) ...
[2010/03/01 01:33:01] Mirror: Incremental sync of 13 item(s) complete.
[2010/03/01 01:33:01] Mirror: Volume 8001 sync complete. Mirror active.
[2010/03/01 01:34:57] Volume 8001 ("G:") mirror is ACTIVE.
[2010/03/01 01:34:57] Volume 853C ("E:") mirror is ACTIVE.
GETSTATS command
This command provides the ability to fetch real-time statistics from the server remotely by requesting a static number from the server that corresponds to the desired function.
Syntax
The syntax for the GETSTATS command is:
FCPUTIL [ -s | -S ] GETSTATS [ <stat-IDs> ... ]
Statistics IDs
Here is a full list of the Statistic IDs and their values. Commonly used statistics are set apart in blue.
Statistic Name |
Statistic ID# |
Description |
|
|
|
Subsystem stats |
|
|
General stats |
|
|
StatCounter |
0 |
starts at 1, increments every time stats are returned |
Sanity |
1 |
always returns a value of 1 |
Version |
2 |
always returns the current server version (e.g. 8.000) |
Build |
3 |
always returns the current server build number (e.g. 200.0) |
|
|
|
Task stats (incremental) |
|
|
LastReset |
1000 |
milliseconds since previous stats reset |
Loops |
1101 |
iterations through task list |
Tasks |
1102 |
total number of tasks scheduled |
IO |
1103 |
I/O operations requested |
AsyncIO |
1104 |
I/O operations gone async (IOList) |
Idle |
1105 |
times Idler scheduled |
WakeIdle |
1106 |
times sleeping tasks wake due to idle |
Suspend |
1107 |
times tasks removed from ready list |
HotTasks |
1108 |
times tasks scheduled from hot list |
Longest |
1109 |
longest latency on task loop for interval |
|
|
|
Task stats (cumulative) |
|
|
TLoops |
1201 |
iterations through task list |
TTasks |
1202 |
total number of tasks scheduled |
TIO |
1203 |
I/O operations requested |
TAsyncIO |
1204 |
I/O operations gone async (IOList) |
TIdle |
1205 |
times Idler scheduled |
TWakeIdle |
1206 |
times sleeping tasks wake due to idle |
TSuspend |
1207 |
times tasks removed from ready list |
THotTasks |
1208 |
times tasks scheduled from hot IO list |
TLongest |
1209 |
longest latency on task loop over period |
TAverage |
1210 |
average latency on task loop over period |
|
|
|
File stats (incremental) |
|
|
Opens |
1301 |
total number of file open *requests* |
Reads |
1302 |
read operations requested |
ReadHits |
1303 |
read operations satisfied from SAFile cache |
ReadSysHits |
1304 |
read operations satisfied from file system cache |
ReadBytes |
1305 |
bytes transferred during read operations |
Writes |
1306 |
write operations requested |
WriteHits |
1307 |
write operations satisfied from SAFile cache |
WriteSysHits |
1308 |
write operations satisfied from file system cache |
WriteBytes |
1309 |
bytes transferred during write operations |
|
|
|
File stats (cumulative) |
|
|
TOpens |
1401 |
total number of file open *requests* |
TReads |
1402 |
read operations requested |
TReadHits |
1403 |
read operations satisfied from SAFile cache |
TReadSysHits |
1404 |
read operations satisfied from file system cache |
TReadBytes |
1405 |
bytes transferred during read operations |
TWrites |
1406 |
write operations requested |
TWriteHits |
1407 |
write operations satisfied from SAFile cache |
TWriteSysHits |
1408 |
write operations satisfied from file system cache |
TWriteBytes |
1409 |
bytes transferred during write operations |
|
|
|
Other file stats |
|
|
Open |
1400 |
total number of files currently open |
|
|
|
FirstClass server stats |
Timed performance statistics |
|
|
MS |
2001 |
milliseconds for this period |
TPL |
2002 |
ticks per loop |
LPS |
2003 |
loops per second |
TPS |
2004 |
task switches per second |
Usage |
2005 |
the Task Load indicator (percentage) |
|
|
|
The other two Summary load bars |
|
|
DiskAvg |
2011 |
average disk response time (including server overhead) |
DiskLoad |
2012 |
same as above but converted to arbitrary load % bar |
ServerAvg |
2021 |
average server response time |
ServerLoad |
2022 |
same as above but converted to arbitrary load % bar |
|
|
|
Disk operations (system requests) |
|
|
DiskOps |
2030 |
total # disk ops (incrementing) |
DiskOpsMTA |
2031 |
total # disk ops by the superhot task, typically the MTA (incrementing) |
|
|
|
Snapshot server statistics |
|
|
Modems |
2101 |
current number of modem connections |
Connected |
2102 |
current number of network connections (including remote) |
Priority |
2103 |
0=prDedicated (High), 1=prSharedApp (Med), 2=prBackground (Low) |
SessionLED |
2104 |
0=normal, 1=warning, 2=usage at or beyond 100% |
Logins |
2105 |
total number of logins |
Remote |
2106 |
current number of remote session licenses in use (requires 8.0 Build 242 server or later) |
|
|
|
Other misc server stats |
|
|
SessionLimit |
2110 |
per-session memory limit |
AuditProgress |
2111 |
complete, or 100 if not running
|
|
|
|
Server Monitor times |
|
|
LastFileReset |
2201 |
last "Reset" for "Files" tab or server start time |
LastTaskReset |
2202 |
last "Reset" for "Tasks" tab or server start time |
ServerBoot |
2203 |
server startup time |
|
|
|
Message queue stats |
|
|
Deliveries |
2301 |
messages delivered |
Active |
2302 |
messages awaiting immediate delivery |
Urgent |
2303 |
urgent messages queued |
UrgentQ |
2304 |
percentage of queue filled |
Normal |
2305 |
normal messages queued |
NormalQ |
2306 |
percentage of queue filled |
Bulk |
2307 |
bulk messages queued |
BulkQ |
2308 |
percentage of queue filled |
Junk |
2309 |
junk messages queued |
JunkQ |
2310 |
percentage of queue filled |
Held |
2311 |
held messages queued |
HeldQ |
2312 |
percentage of queue filled |
Delayed |
2313 |
delayed messages queued |
DelayedQ |
2314 |
percentage of queue filled |
|
|
|
System stats |
|
|
Memory stats |
|
|
MemAppTotal |
9001 |
total system memory available to the server, after limiting factors (e.g. address space) |
MemAppAvail |
9002 |
available system memory for server use, after limiting factors (e.g. address space) |
MemVirtTotal |
9003 |
total virtual memory on the server machine |
MemVirtAvail |
9004 |
virtual memory available to the server on the server machine |
MemAddrTotal |
9005 |
total address space for the server process |
MemAddrAvail |
9006 |
address space currently available for the server use |
MemPhysTotal |
9007 |
total physical memory on the server machine |
MemPhysAvail |
9008 |
available physical memory on the server machine |
Examples
This command returns the three server load percentages normally displayed on the Summary tab of the Server Monitor.
FCPUTIL GETSTATS 2005 2012 2022
The output would be something like:
C:\>FCPUTIL GETSTATS 2005 2012 2022
FCPUtil Version 8.0.5 [Nov 22 2004]
Copyright (c) 2004 by Open Text Corporation
Stat ID Current Statistic Value
======= =======================
2005 0.000
2012 0.220
2022 0.000
3 statistics returned.
Note
If no stat IDs are specified, FCPUTIL uses a default list of "2 3 2005 2012 2022 1400 2111 2301 2302 9002".
For the purposes of more automated procedures, there are two options (-s and -S) to reduce the complexity and verbosity of the output.
-s returns an "ID=value" formatted list:
C:\>FCPUTIL -s GETSTATS 2005 2012 2022
2005=0.000 2012=0.235 2022=0.000
-S just returns a list of values:
C:\>FCPUTIL -S GETSTATS 2005 2012 2022
0.000 0.358 0.000
A common example for tracking server performance might be the default stats list in the terse format:
C:\>FCPUTIL -S GETSTATS
8.000 203.000 0.000 0.231 0.000 44.000 100.000 0.000 0.000 1072410624.000
| 
Note