Errors

 Overview

Communications packages, by their nature, generate a large number of text messages, return codes, and the like. UPSTREAM provides superior message handling allowing you to understand and solve whatever problems occur.

Many of the UPSTREAM messages that are reported are accompanied by TCP/IP return codes, operating system messages, and more. To aid in problem determination, system administrators should have access to all communication package documentation, especially those related to TPC/IP return codes and operating system messages.

This section discusses how messages are displayed, how they are stored, and what they mean.

See UPSTREAM Messages for the messages.

 Problem Reporting

Our customers are very important to us. Our goal is always to provide prompt and courteous service.

Should you have any questions regarding the installation, implementation, or use of the UPSTREAM program product, please feel free to contact BMC Support.

In the event you are having difficulty with UPSTREAM, please retain all the error information you can gather and contact BMC Support as soon as possible. We will make every effort to resolve the difficulty in the shortest possible time.

How Messages are Displayed

Messages generated in the UPSTREAM program (US.EXE) and the UPSTREAM Configurator (USCFG.EXE) are displayed as message dialogs with two buttons, OK and Hold. When you press the OK button, the message window goes away, when you press the Hold button any message time-out is ignored and the message remains on the window until you press the OK button.

The message dialog can also go away after a given amount of time if you specified a Messages Time Out in the UPSTREAM Configurator. The amount of time remaining is displayed in the lower left corner of the message dialog; if you do not specify a Messages Time Out then No Msgs Time Out Set is displayed. You can also disable messages entirely (though this is not recommended - it can be confusing when using in an attended mode) with a Messages Time Out value of -1.

UPSTREAM displays a Messages list box in the status dialog for backups, restores, file transfers and physical disk backups/restores. The standard UPSTREAM Message window is not displayed; messages are written directly to this list box. This allows you to be able to view prior messages while the operation is in progress with little performance overhead. Thus “Messages Time Out” is much less important during these operations as it is only used during setup and completion. We still recommend that it be set to a non-zero value (so that message windows get timed out), but it can be higher (for example, 30 seconds). If you are running in attended mode, the UPSTREAM log viewer is automatically displayed if a backup or restore fails.

There is a new parameter in the UPSTREAM Configurator/Advanced options: Max Status Msg Lines. Since list boxes in many environments cannot contain a large number of lines, you specify here the maximum number of lines in the list before the oldest messages are removed. You can specify 0 to indicate no limit (not recommended) or -1 to suppress screen logging (which may improve speed slightly). The default is 500 and the configuration parameter is MAXSTATUSMSGLINES.

Messages may come from two different sources: UPSTREAM locally and the Storage Server. Figures below shows a message from UPSTREAM workstation/server and a message generated by the Storage Server and displayed by UPSTREAM locally. Note that the UPSTREAM Storage Server message is in upper case and that it is always accompanied by workstation/server message #1402.

Both of the figures above show UPSTREAM displaying more than one message at a time in a single message window. This allows you to know as much as possible about the environment to assist you in your problem determination.

Messages are truncated to fit in 55 characters for display and transmission to the UPSTREAM Storage Server. The full message is written to the log.

The Message Log

The message log is a file where significant system messages are written. These messages may or may not have been written to the screen.

The message log file is a standard text file, and you can display it, print it, edit it or read it with standard text file programs (TYPE, PRINT, EDIT, etc.). The name of the log is configurable in the configurator. The default name and directory is:

{{id name="Errors-135_JCL_1071548"/}}

{{id name="Errors-1071548"/}}

C:\Program Files\Innovation Data Processing\UPSTREAM\UPSTREAM.LOG\\The following is an example of messages in the message log.

{{id name="Errors-135_JCL_1077775"/}}

{{id name="Errors-1077775"/}}

Mon Jun 17 15:25:41 1991
 Msg #PC2050I Backup started
Mon Jun 17 15:26:10 1991
 Msg #PC2051D Backup successful
 5 files 7988 bytes 469 chars/sec
Wed Jun 19 12:08:07 1991
 Msg #PC2150I Restore started
Wed Jun 19 12:08:12 1991
 WORKSTATION NAME FAILED CONFIGURATION VERIFICATION
 Msg #PC1402E Remote system error
 The preceding message was from the remote system.
 Subsequent messages describe where in the PC
 the error occurred and can usually be ignored.
 Msg #PC2102E Error occurred during a restore receive descript
 Msg #PC1705E Error occurred during a RECEIVE_AND_WAIT verb
Wed Jun 19 12:08:42 1991
 Msg #PC2153I Restore failed\\If there is an error writing to the log file during the backup, UPSTREAM retries for 5 seconds and then writes those messages (along with the reason that it could not write to the log file) to an alternate log file UPSERR.ERR. This process is repeated for subsequent errors writing to the log file.

If UPSTREAM cannot write to UPSERR.ERR, a MessageBox is displayed that shows the message file error number for the location of the failure.

Error and Warning messages are also sent to the UPSTREAM Storage Server if there is an active conversation. You can also send the detail for reported messages to the UPSTREAM Storage Server (rather than just the first line) for backups by setting the parameter SENDHOSTDETAILS to Y. Additional message text from the message file is not sent. You can set this from the More dialog, by checking Send message details to host. The default is not checked.

UPSTREAM Director and Logging

The UPSTREAM Director does not log any errors itself (though it may display message boxes), however you can see errors for the systems that you are connected to by pulling down the View menu, then select the Messages sub-menu and the system whose messages you want to view (such as Current Target).

If you wish to view the entire log from an UPSTREAM system in the Target Systems list, you can press the Log button that causes the entire log to be transmitted from the remote system. For large logs this may take several seconds.

The UPSTREAM Director has extensive tracing available, by modifying the usdir.bat file. Contact BMC Support to determine when this is needed, assistance in setting it up and interpreting it.

 USLOGCLR (Clearing the Log)#

USLOGCLR is a program that is distributed with UPSTREAM that helps you maintain the message log (UPSTREAM.LOG, USSTART.LOG, and USNDS.LOG) and the report files. Since the message log and the report files are standard text files, it grows as messages continue to be added. Therefore, UPSTREAM distributes a program that shrinks the log and keeps it to a manageable size.

For the default log, you can have it automatically cleared during backups with the MAXLOGDAYS parameter. For the active report, you can have it automatically cleared during backups with the MAXRPTDAYS parameter. As for USLOGCLR, if you specify a non-zero value for these parameters, UPSTREAM keeps only the specified number of days worth of information. These parameters only applies to the default UPSTREAM log or active report, not any of the other log files that UPSTREAM may maintain on the system (USLN.LOG, MSEXCH.LOG, etc.).

USLOGCLR allows you to reduce the size of the log by the number of days worth of log information that you wish to maintain. You run USLOGCLR from the command line with command line parameters.

The syntax for USLOGCLR is:

{{id name="Errors-135_JCL_1064149"/}}

{{id name="Errors-1064149"/}}

USLOGCLR <Number of days old> <Log file name>\\Where:

<Number of days old>

is a number from 0 to 32767 that indicates the entries that have been in the log longer than these number of days is purged.

<Log file name>

is an optional parameter that is the name of the log or report file to clean. If you do not specify anything, the default of UPSTREAM.LOG is used.

If you run USLOGCLR.EXE without any parameters it displays a brief description of its calling conventions.

For example, if you wish to clean out all but the last 14 days of information from the default log, you would run USLOGCLR as follows:

{{id name="Errors-135_JCL_1064162"/}}

{{id name="Errors-1064162"/}}

USLOGCLR 14\\As USLOGCLR runs, it writes the log entries it wishes to save to a temporary file, and then deletes the original log and renames the temporary file. Therefore, it is required that you have a certain amount of free disk space.

USLOGCLR writes to the screen the number of lines removed and the number of lines remaining. This information can be redirected with standard I/O redirection if you do not wish any display.

(NLM) /a is an optional switch to be used after the parameters above are specified. If specified, the screen group is removed even if there is an error (AutoScreenDestructionMode)

24.6 The Message File

Almost all UPSTREAM messages for both the Configurator (USCFG.EXE) and the UPSTREAM program (US.EXE) are stored in the message file. The default name for the message file is UPSTREAM.MSG and you can change the name in the advanced configurator.

The message file is a standard DOS text file which can be viewed, printed or edited with standard DOS facilities (TYPE, PRINT, EDLIN, etc.). The format for messages in the log is:

{{id name="Errors-135_JCL_1064201"/}}

{{id name="Errors-1064201"/}}

[NUMBER][SEVERITY] [TEXT]
 [ADDITIONAL TEXT]
 …
 [ADDITIONAL TEXT]
{ NEXT MESSAGE }\\Where:

NUMBER

The message number is a 4-digit number that the programs look for when they have a particular message to log.

SEVERITY

The severity is a single letter indicating what to do with the message. If the severity is a lower case letter and the message is displayed, then the message does not time out regardless of the Message Time Limit setting. There are several severities that include:

I - Informational message. These messages are only written to the log. The messages are not displayed or sent to the remote system. An example is a message indicating that there was an error during the restore and the message was already displayed.

N - Display but do not log. These messages are only displayed on the screen. The messages are not written to the log or sent to the remote system. Examples are Configurator messages that do not need to be written to the log.

D - Display and log. These messages are displayed and written to the log but not sent to the remote system. Examples include statistics messages after transfers are complete.

W - Warning. These messages indicate that a significant, but not necessarily fatal event, has occurred. These messages are logged, displayed and sent to the remote system. An example would be during a restarted backup, when the backup must restart from the beginning. This is significant, but the operation can continue.

E - Error. These messages indicate that an error has occurred. The messages are usually (but not always) fatal. These messages are logged, displayed and sent to the remote system. Examples would be file errors during a backup.

TEXT - This is text that describes the message.

ADDITIONAL TEXT - Any additional lines of text that you wish logged or displayed (up to a total for the window of 10 lines). Each line of text must have a character in column 1.

There are several advantages with this scheme:

• 135_List1_Bullet_1064237 • You can change the message text. If you wish to customize the messages for your installation you can. This also simplifies foreign language issues.
  
• 135_List1_Bullet_1071010 • You can change the message severity. For example, if you wished that statistics not be displayed to users, you could change the severity from D to I.
  
• 135_List1_Bullet_1071011 • You can find messages in your message file. If you are performing problem determination for a user, you can use your text editor to find the message associated with a message number in your copy of the message file.
  
• 135_List1_Bullet_1064240 • Program size is decreased. UPSTREAM does not contain the text for these messages in its code.
  

If the message file is not found, or there is an error reading the message file, the message is handled as if it had severity E, and you see a message logged in place of the normal text that can include:

Error reading msg file: <error text>

This means that there was a file error reading through the message file. The file error text describes the DOS error.

Message not found.

The message that is requested by UPSTREAM was not found in the message file.

Error opening msg file: <error text>

There was an error when UPSTREAM attempted to open the file to log a message. The file error text describes the error encountered.

Message file not defined

This means that the message file name was not defined or removed from the Advanced Configurator.

If you choose to modify the message file, remember the following guidelines:

• 135_List1_Bullet_1064257 • Each message can be no more than 56 characters long.
  
• 135_List1_Bullet_1064258 • There can be no more than 10 lines of message text in a message window. The safest route is to not add any more additional message text than exists currently.
  
• 135_List1_Bullet_1064259 • New messages begin with a number in column 1.
  
• 135_List1_Bullet_1064260 • The end of each message’s additional text is denoted with a non-blank in column 1.
  

TCP/IP Messages

TCP/IP Messages are displayed as UPSTREAM messages PC4800-4899. See UPSTREAM Messages for a listing of these and all other UPSTREAM messages.

Since each TCP/IP implementation uses different message numbers, UPSTREAM maps these messages into the z/OS UNIX Systems Services E messages and then to UPSTREAM messages in the above range.

For details about remedies for a specific message you need to see your TCP/IP documentation. These messages are also briefly described in Performance.

Operating System Messages

Operating system messages are those messages that the operating system reports when an action is attempted that fails, usually file access. These messages can be reported in two ways:

• US.EXE, USCFG.EXE, and ULTRA.EXE attempt to find the error text associated with the message and display the text as an additional message. If the text is unknown, then the error number itself is displayed.
  
• USSTART.EXE reports ALL operating system errors with the number alone.
  

OS/2 operating system numbers can be interpreted by entering from an OS/2 Window or Full screen:

HELP SYS<number>

Windows operating system numbers can be interpreted by entering from a DOS window:

{{id name="Errors-135_JCL_1071642"/}}

{{id name="Errors-1071642"/}}

NET HELPMSG <number>\\The meaning of the UNIX operating system message numbers (if not displayed) can be found in the /usr/include/errno.h or /usr/include/sys/errno.h files.

If the text is not displayed or you have questions concerning message interpretation contact BMC Support for assistance.