Data Warehouse Center Application Integration Guide

Returning status information

After your Data Warehouse Center program runs, it must return a return code to the step that uses the program. The return code must be a positive integer. If your program does not return a return code, the step using the program fails. The Data Warehouse Center displays the return code in the Error RC2 field of the Log Details window when the value of Error RC1 is 8410.

Your Data Warehouse Center program can return additional status information to the Data Warehouse Center:

Another return code, which can be the same as or different from the code that is returned by the Data Warehouse Center program.
A warning flag that indicates that the Data Warehouse Center is to treat the return code as a warning. When your program sets this flag, the step that uses this program will have Warning status in the Operations Work in Progress window.
A message, which is displayed in the System Message field of the Log Viewer Details window
The number of rows of data that the program processed.
The Data Warehouse Center displays the number in the Log Viewer Details window for the step.
The number of bytes of data that the program processed.
The Data Warehouse Center displays the number in the Log Viewer Details window for the step.
The SQLSTATE return code, which the Data Warehouse Center displays in the SQL state field of the Log Viewer Details window.

The Data Warehouse Center agent transfers the additional status information to the warehouse server.

Transferring the information to the Data Warehouse Center

To transfer the additional status information to the warehouse agent, your program must create a file, called a feedback file, containing the additional status information. The path and file name for the feedback file must be the value of the VWP_LOG environment variable. (The file name is processid.log, where processid is the ID of the agent process.) The agent sets VWP_LOG before it calls the program. After the program finishes running, the agent checks whether the feedback file exists. If it exists, the agent processes the file. Otherwise, the agent will do nothing. If the program cannot create the file, it should continue to run.

Format of the feedback file

Your program can write the additional status information to the feedback file in any order, but must use the following format to identify information. Enclose each returned item within the begin tag <tag> and end tag </tag> in the following list. Each begin tag must be followed by its end tag; you cannot include two begin tags in a row. For example, the following tag format is valid:
<RC>...</RC>...<MSG>...</MSG>
The following embedded tag format is not valid:
<RC>...<MSG>...</RC>...</MSG>

You can specify the following information in the feedback file:

Return code

<RC>return code</RC>, where return code is a positive integer.

Return code warning flag

<WARNING>1</WARNING> sets the return code warning flag to On.

Data Warehouse Center system message

<MSG>message text\n</MSG>

message text: The text of one or more messages
\n: The new line character. Include this character at the end of each message if there are multiple messages.

Comment

<COMMENT>comment text</COMMENT>, where comment text is the text of the comment.

Number of rows of data processed

<ROWS>number of rows</ROWS>, where number of rows is any positive integer.

Number of bytes processed

<BYTES>number of bytes</BYTES>, where number of bytes is any positive integer.

SQLSTATE

<SQLSTATE>sqlstate string</SQLSTATE>, where sqlstate string is any string whose length is greater than 0 and less than or equal to 5 digits.

Figure 77 shows an example of the feedback file.

Figure 77. Example of the feedback file

<RC> 20</RC> <ROWS>2345</ROWS> <MSG>The parameter type is not correct</MSG> <COMMENT> Please supply the correct parameter type (PASSWORD NOTREQUIRED, GETPASSWORD, ENTERPASSWORD)</COMMENT> <BYTES> 123456</BYTES> <WARNING> 1</WARNING> <SQLSTATE>12345</SQLSTATE>

How the feedback determines the step status

The return codes and step status for the program that are displayed in the Log Viewer vary. They depend on the following values set by the program:

The value of the return code that the program returned
Whether a feedback file exists
The value of the return code in the feedback file
Whether the warning flag is set to On

Table 144 lists the possible combinations of these values and the results that they produce.

Table 144. Feedback file conditions and results

Conditions Results
Step status¹ Values of Error RC1 and RC2
Data Warehouse Center program return code is 0 No feedback file exists² Successful
RC1 = 0; RC2 = 0
A feedback file exists² The value of <RC> in the feedback file is 0³ <WARNING> is not set in the feedback file Successful
RC1 = 0; RC2 = 0
The value of <WARNING> in the feedback file is 1 Warning
RC1 = 0; RC2 = 0
The value of <RC> in the feedback file is non-0³ <WARNING> is not set in the feedback file Failed
RC1 = 8410 (the program failed); RC2 = the value of <RC> in the feedback file
The value of <WARNING> in the feedback file is 1 Warning
RC1 = 0; RC2 = the value of <RC> in the feedback file
The Data Warehouse Center program return code is nonzero No feedback file exists² Failed
RC1 = 8410 (the Data Warehouse Center program failed); RC2 = the code returned by the Data Warehouse Center program
A feedback file exists² The value of <RC> in the feedback file is 0³ <WARNING> is not set in the feedback file Successful
RC1 = 0; RC2 = 0
The value of <WARNING> in the feedback file is 1 Warning
RC1 = 0; RC2 = 0
The value of <RC> in the feedback file is non-0 <WARNING> is not set in the feedback file Failed
RC1 = 8410 (the Data Warehouse Center program failed); RC2 = the code returned by the Data Warehouse Center program
The value of <WARNING> in the feedback file is 1 Warning
RC1 = 0; RC2 = the value of <RC> in the feedback file

Notes:

The step processing status, which is displayed in the Work in Progress window.
The Data Warehouse Center checks for the existence of the feedback file, regardless of whether the return code for the program is 0 or nonzero.
The Data Warehouse Center always displays the value of <RC> in the feedback file as the value of the RC2 field in the Log Details window.

Conditions	Results
Step status¹	Values of Error RC1 and RC2
Data Warehouse Center program return code is 0	No feedback file exists²	Successful	RC1 = 0; RC2 = 0
A feedback file exists²	The value of <RC> in the feedback file is 0³	<WARNING> is not set in the feedback file	Successful	RC1 = 0; RC2 = 0
The value of <WARNING> in the feedback file is 1	Warning	RC1 = 0; RC2 = 0
The value of <RC> in the feedback file is non-0³	<WARNING> is not set in the feedback file	Failed	RC1 = 8410 (the program failed); RC2 = the value of <RC> in the feedback file
The value of <WARNING> in the feedback file is 1	Warning	RC1 = 0; RC2 = the value of <RC> in the feedback file
The Data Warehouse Center program return code is nonzero	No feedback file exists²	Failed	RC1 = 8410 (the Data Warehouse Center program failed); RC2 = the code returned by the Data Warehouse Center program
A feedback file exists²	The value of <RC> in the feedback file is 0³	<WARNING> is not set in the feedback file	Successful	RC1 = 0; RC2 = 0
The value of <WARNING> in the feedback file is 1	Warning	RC1 = 0; RC2 = 0
The value of <RC> in the feedback file is non-0	<WARNING> is not set in the feedback file	Failed	RC1 = 8410 (the Data Warehouse Center program failed); RC2 = the code returned by the Data Warehouse Center program
The value of <WARNING> in the feedback file is 1	Warning	RC1 = 0; RC2 = the value of <RC> in the feedback file
Notes: The step processing status, which is displayed in the Work in Progress window. The Data Warehouse Center checks for the existence of the feedback file, regardless of whether the return code for the program is 0 or nonzero. The Data Warehouse Center always displays the value of <RC> in the feedback file as the value of the RC2 field in the Log Details window.

[ Top of Page | Previous Page | Next Page ]