Command line logging is supported through the use of the PBLog.exe program. This is useful when logging from batch files or shell scripts or for simply adding a comment inline like, “Starting test suite 7 now…”. It is installed to the system32 directory so it is always on the path and can be invoked from the command line or from the Start | Run menu pick on the task bar.
The syntax is:
PBLog.exe [OPTIONS] [message text]
Switch
Option
Usage
Remarks
-?
Display help
Displays command line help.
-H
Display help
Displays command line help.
-M
Message type
Followed by one of: NVISWEBRCU[nnn]
Example: -MV logs a VERBOSE message
-C
Component
-CMyComponent
-K
MessageKey
-ASomeMessageKey
-X
Context
-XTheContext
-O
Module
-OW:\Bin\MyScript.csh
-F
File
-FW:\Bin\MyScript.csh
-L
Line
-L123
Decimal is always assumed.
-P
PID
-P0x1234
Hex is assumed. ‘0x’ prefix is not required.
-T
TID
-T0x1234
Hex is assumed. ‘0x’ prefix is not required.
-N
NoReturnCodes
Followed by 'T' or 'F'.
Enables/disables diagnostic return codes.
--
End of options
--
All remaining args are message text.
Syntax
Either a dash (-) or forward slash (/) may be used to introduce options.
A double dash (--) or double forward slash (//) is used to indicate the end of options. This is useful for logging messages that begin with a dash or forward slash.
All option switches are case insensitive. /M and /m are equivalent.
All options with arguments assume a single string with no spaces following. If the arguments contain spaces then they will need to be quoted. E.g. “/CMy Component”.
All unsupplied text fields including Module and File will default to empty strings and all numeric fields default to 0.
If no message type is specified then COMMENT is used.
Message type specifiers are case insensitive and may be fully spelled out for readability since only the first single character after the /M is evaluated. I.e. /MV, /Mv, /Mver, and /MVerbose will all log a message of type VERBOSE.
If message type is USER then the ‘/MU’ option must be followed by a number which may be specified in decimal or hex. Hex is indicated by prefixing the number with ‘0x’. The number will be treated as a 16 bit quantity and shifted 16 bits to the left to create the final message type field of the log message. A number equal to 0 or larger than 64K will be treated as invalid. E.g. “/MUSER123” or “/MU0xABCD”.
Message text is not required and will simply log an empty string if not provided.
If message text is provided then it does not need to be quoted since all arguments to PBLog.exe are simply concatenated. Hence the statement ‘PBLog /S Hello world.’ will simply log the single string “Hello world.” as a STATUS message.
Remarks
The Process field was omitted deliberately for reasons of audit integrity. We thought it important to have at least one field that differentiates PBLog.exe generated messages from other messages since with so many configurable fields, messages from PBLog.exe can easily be accidentally or intentionally misleading. Process was the least informative field (C:\WinNT\System32\CMD.exe), says ‘PBLog.exe’ with no extra coding, and collided with /P[ID] anyway.
Module and File were both left in chiefly because there was no reason to take one out. They are just unrestricted text fields and can be used in any manner suitable. They can be used together to indicate extra information like procedure name if desired. Note that filter and display operations will assume these fields are fully specified file paths so the use of forward or backward slashes (‘/’ or ‘\’) in the strings will affect things accordingly.
PID and TID are supported so that messages logged from various threads of various command processors can all be kept organized.
Environment variables may be used in place of any of the command line options except Message type and Line. Each variable consists of the string PBx where x is one of the option switches discussed above. E.g. the command line statement ‘set PBT=0x1234’ will cause all subsequent instances of PBLog.exe launched with the same environment to use 0x1234 for the TID field just as if they were invoked with /T0x1234 as one of the command line options. Note that options passed on the command line override those in the environment.
If the NoReturnCodes option is true (the default), PBLog.exe will always return zero. If set to false, PBLog.exe will return zero for success or -1 if any errors occur during the call.
If the command line is formatted incorrectly (e.g. unrecognized option), the message will still be logged interpreting as many parameters as possible, and additionally an internal notification (2000) will be generated informing of the error. If NoReturnCodes is enabled, a non-zero error will be returned.