Body

The Universal Agent allows for various data providers in order to create custom applications to gather monitoring metrics.

The definitions for a custom application are specified in metafiles.

This blog post is to provide debugging details for using the POST data provider, and utility program KUMPSEND.

Post Data Provider

https://www.ibm.com/support/knowledgecenter/SSTFXA_6.2.3/com.ibm.itm.doc_6.2.1/621uausers137.htm#postdp

#1)  Confirm the UM component version and platform for the environment

On UNIX / Linux, check the "cinfo -i" output -  on Windows, check "kincinfo -d".  Or provide "pdcollect" output file from the UM agent system.

#2) Confirm the syntax of any "kumpsend" command used.

#3) Provide a copy of the KUMPOST metafile from the environment.

The  KUMPOST metafile must be located in the KUMP_META_PATH directory, which is typically the standard \metafiles subdirectory.  First confirm the KUMP_META_PATH= value used on the failing environment, provide the "KUMPOST" metafile that is handling POST data provider settings.
https://www.ibm.com/support/knowledgecenter/SSTFXA_6.2.1/com.ibm.itm.doc_6.2.1/621uausers142.htm

A common problem reported is where the post category is not displayed as expected for the message, resulting in situation alerts that rely on the category value not triggering.

Message categories
There are ten predefined post message categories, shown in Table 9.
The meaning of each category is determined by your data and local usage guidelines.
Category Description
Table 9. Post Data Provider message categories
I Information
O Operation
P Application
S System
N Network
A Alerts
C Critical
W Warning
R Reset
D Detail

The ITM Universal Agent allows users to customize the KUMPOST metafile used by the POST data provider,  allowing to change or add attributes after the first 3, which should not be modified according to the manual:
http://publib.boulder.ibm.com/infocenter/tivihelp/v15r1/index.jsp?topic=/com.ibm.itm.doc_6.2.1/621uausers137.htm

This is why it is important to verify what the KUMPOST metafile contains to confirm the definitions for attributes, specifically the fifth attribute and that it is recognized as "Post_Category" so that the UM knows to translate a single character value specified on "kumpsend" command into a specific category.

If ITM is not recognizing the fifth attribute name specified in the KUMPOST file as "Post_Category" it will not do any translation of the value from the single character that is presented to the data
provider, which can result in a single character value being stored as the attribute value instead of the message category.  For example,  "I" instead of "Information" being sent to the TEMS, and stored as the attribute value.

If the KUMPOST metafile being used has a different name for the attributes (specifically for Post_Category in this case), it will not perform any translation of the incoming data value, and will pass on the attribute value as it was given to the data provider.

Use the "kumpcon validate" command against the KUMPOST metafile to validate its definitions and see if there are any errors reported against the metafile:

Example for failing case where there was a space in the name of the attribute in KUMPOST for "Post Category":

bash$ kumpcon validate KUMPOST
KUMPS001I Console input accepted.
KUMPV025I Processing input metafile C:\ibm\itm\tmaitm6\metafiles\KUMPOST
KUMPV026I Processing record 0001 -> //APPL MAS
KUMPV026I Processing record 0002 -> //NAME dpPost S 3600
KUMPV026I Processing record 0003 -> //ATTRIBUTES ';'
KUMPV026I Processing record 0004 -> Post_Time T 16
KUMPV026I Processing record 0005 -> Post_Origin D 32
KUMPV026I Processing record 0006 -> Post_Ack_Stamp D 26
KUMPV026I Processing record 0007 -> Post_Text U 2000
KUMPV054W Specification Warning: Attribute maximum size changed to 4000 from 6000.
KUMPV026I Processing record 0008 -> Post Category D 16
KUMPV039E Specification Error: Incomplete attribute definition
KUMPV000I Validation completed successfully
KUMPV090I Application metafile validation report saved in file
C:\ibm\itm\tmaitm6\metafiles\KUMPOST.rpt.

The error above is due to the "KUMPOST" metafile specifying a space instead of an underscore as part of the attribute name for the category column.

Post_TIME  T  16
Post_Origin  D  32
Post_Ack_Stamp  D  26
Post_Text  U  2000
Post Category  D  16

Enable UM RAS1 logging in um.ini (UNIX / Linux) or KUMENV (Windows) to gather detailed tracing to see what values are being received by the POST data provider.

KBB_RAS1=ERROR (UNIT:kump ALL) (UNIT:kumpcadm DETAIL)

Example showing values not "translated" for the category:

kumpplsr.c,311,"KUMP_PostListenService") <0x802B5980,0x20> 125DA64
 00000000   54657374 696E6720  666F7220 446F7567   Testing.for.Doug
 00000010   3B493B00 00000000  00000000 00000000   ;I;.............
.
kum0sttk.c,138,"KUM0_strtok") Calling strtok_r with string1 <Testing for Doug;I;> string2 <;> arrayOfSavePtr[4].savePointer @200012613C0
kum0sttk.c,151,"KUM0_strtok") Returning tok <Testing for Doug> savePointer index 4 @802B5991
kumplpad.c,83,"KUMP_LoadPostAttributeData") Processing attribute <Post_Text> Dptr @802B5980 nextTok 0
kumpiate.c,772,"KUMP_IsNumericAttributeType") Examining attrType <U>
kumplpad.c,149,"KUMP_LoadPostAttributeData") Processing value <Testing for Doug> for display attribute <Post_Text>
kumplpad.c,177,"KUMP_LoadPostAttributeData") Comparing attribute <Post_Text> against <Post_Category>
kumplpad.c,225,"KUMP_LoadPostAttributeData") Checking for next delimiter at offset 17 buffer @802B5991 ATRptr @80361910 BufferLength 32
.
kum0sttk.c,138,"KUM0_strtok") Calling strtok_r with string1 <I;> string2 <;> arrayOfSavePtr[4].savePointer @200012613C0
kum0sttk.c,151,"KUM0_strtok") Returning tok <I> savePointer index 4 @802B5993
kumplpad.c,83,"KUMP_LoadPostAttributeData") Processing attribute <PCategory> Dptr @802B5991 nextTok 17
kumplpad.c,149,"KUMP_LoadPostAttributeData") Processing value <I> for display attribute <PCategory>
kumplpad.c,177,"KUMP_LoadPostAttributeData") Comparing attribute <PCategory> against <Post_Category>
kumplpad.c,225,"KUMP_LoadPostAttributeData") Checking for next delimiter
at offset 19 buffer @802B5993 ATRptr @NULL BufferLength 32

Example from a working environment where the Category is recognized and translated to a category from the single letter used on "kumpsend" command:

kumpplsr.c,311,"KUMP_PostListenService") <0x8035DB80,0x20> 125DA64
  00000000   54657374 696E6720  666F7220 446F7567   Testing.for.Doug
  00000010   3B493B00 00000000  00000000 00000000   ;I;.............
.
kum0sttk.c,138,"KUM0_strtok") Calling strtok_r with string1 <Testing for Doug;I;> string2 <;> arrayOfSavePtr[4].savePointer @200012613C0
kum0sttk.c,151,"KUM0_strtok") Returning tok <Testing for Doug> savePointer index 4 @8035DB91
kumplpad.c,83,"KUMP_LoadPostAttributeData") Processing attribute <Post_Text> Dptr @8035DB80 nextTok 0
kumpiate.c,772,"KUMP_IsNumericAttributeType") Examining attrType <U>
kumplpad.c,149,"KUMP_LoadPostAttributeData") Processing value <Testing for Doug> for display attribute <Post_Text>
kumplpad.c,177,"KUMP_LoadPostAttributeData") Comparing attribute <Post_Text> against <Post_Category>
kumplpad.c,225,"KUMP_LoadPostAttributeData") Checking for next delimiter at offset 17 buffer @8035DB91 ATRptr @802E14F0 BufferLength 32
.
kum0sttk.c,138,"KUM0_strtok") Calling strtok_r with string1 <I;> string2 <;> arrayOfSavePtr[4].savePointer @200012613C0
kum0sttk.c,151,"KUM0_strtok") Returning tok <I> savePointer index 4 @8035DB93
kumplpad.c,83,"KUMP_LoadPostAttributeData") Processing attribute <Post_Category> Dptr @8035DB91 nextTok 17
kumplpad.c,149,"KUMP_LoadPostAttributeData") Processing value <I> for display attribute <Post_Category>
kumplpad.c,177,"KUMP_LoadPostAttributeData") Comparing attribute <Post_Category> against <Post_Category>
kumplpad.c,195,"KUMP_LoadPostAttributeData") Copying category value <Information> to AttrName <Post_Category>
kumplpad.c,225,"KUMP_LoadPostAttributeData") Checking for next delimiter at offset 19 buffer @8035DB93 ATRptr @NULL BufferLength 32

In the above, the POST data provider is receiving "I" as the category value based on the kumpsend command used.

In the failing case, the "KUMPOST" metafile specified a space instead of an underscore as part of the attribute name for the category column which is then interpretted as PCategory instead of Post_Category.

The UM is specifically looking for an exact match to the attribute name "Post_Category".  If there are differences in the name including casing, this can result in the UM considering the field as a "custom" user defined field and not one of the pre-defined fields the UM expects for the POST data provider, and the UM will not translate the value into any of the defined categories.

In the working case, ITM Universal Agent translates "I" to "Information" before sending the data to the TEMS when the "attribute" name specifically matches "Post_Category".

...

Along with there being possible problems in the KUMPOST metafile, a failing environment may have customized the categories with KUMP_POST_CATEGORY= settings which could be specific to the value sent in kumpsend command for the "cat=" value.

It is necessary to verify the syntax of the "kumpsend" command that is failing to display a category.

Example syntax:
kumpsend dp=xxx.x.xxx.xxx msg=test cat=D ack=y

*NOTE* The KUMPSEND program only works with the default 5 predefined attributes.  Any change in a name (including casing) and the attributes are not the expected "default" anymore.

Then review the failing environment to see if it is setting any environment / configuration value for KUMP_POST_CATEGORY= parameter, which can alter the default list of categories.

Users can add to, redefine, or remove the default category definitions. A maximum of 16 message categories is possible.

For example, the following definition adds the category X to the Post Data Provider:

KUMP_POST_CATEGORY=(X=Experimental)

This definition redefines category P from Application to Programming:

KUMP_POST_CATEGORY=(P=Programming)

This definition removes category D:

KUMP_POST_CATEGORY=(D=)

This definition specifies all three of the previous definitions in one statement:

KUMP_POST_CATEGORY=(X=Experimental,P=Programming,D=)

*NOTE* Any predefined category that is not explicitly redefined or removed remains unchanged.

Additional information:

KUMPSEND provides following 'return codes', as noted in UA Users' Guide:

 
0 = Success
1 = Invalid local socket environment
2 = Input parameter error
3 = Failure to contact Target DP
 
It is up to author of a custom client program, i.e. customer's Java program, to define and implement whatever 'return codes', if any.
 
 Page 59 of Universal Agent User's Guide documents what is returned by the UA's POST Data Provider when connecting to it via TCP/IP.
***
Acknowledgment stamp
The Post Data Provider generates an acknowledgment stamp to uniquely identify each message received from an application.
The stamp is returned to the sending application only if the application is connected to the Post Data Provider by a connection-oriented TCP socket.
 
For UDP sockets, the stamp is internally associated with the received message, but it is not returned.  Using the acknowledgment stamp, you can quickly track and identify all Post Data Provider messages while in the system.
 
The stamp AAAAAAAATTTTTTTTTTTTCSSSSS is comprised of four parts where:
 
AAAAAAAA.       is the origin of the message
TTTTTTTTTTTT  is the local time of message arrival
C                        is the message category
SSSSS               is the message one complement check sum

***

Submitter: drd401709
Compid: 5724K1000
Reference DCF technotes:

Keywords:
UA UM kuma620 kuma620.exe