T4S4  19.1 C8540 A23673
Teamcenter Gateway for SAP S/4HANA API Reference
LOG handling

Functions

 createLogChannel LogChannel
 This functions initializes the search index for the specified log channel. More...
 
 getBinLogFile logchannel target zip
 This function downloads a binary logfile from the BGS server and stores this in the local filesystem. More...
 
 setSecurityContext4LogChannel LogChannel SecurityContext
 Sets the security context of a given logchannel. More...
 
 storeBinLogFile src logchannel
 This function upload a binary logfile to the BGS server. More...
 
 testLogPattern logchannel pattern
 Test the last line of a logfile for a keyword. More...
 
 tpco_getListOfValues
 This function returns all occurring values for a certain key (without duplicates) as well as the number of absolute occurrences for each found value. More...
 
 tpco_getLogIndex
 This function returns the key attribute list of a specified log channel, matching the given patterns for key and value. More...
 
 tpco_removeLogIndex
 This function removes an attribute entry from the specified log channel. More...
 
 tpco_searchGlobLogIndex
 This function simply searches globally for all terms defined in searchlist within the whole log index. It returns a list of matching log index entries. More...
 
 tpco_searchLogIndex
 This function can search for several specific keys and values at once. It returns a list of matching log index entries, which can be used to get the corresponding log files. If the key is defined as “*” and the value is defined as “*”, all entries are returned. More...
 
 tpco_setdlogchannel
 This function sets the default logchannel for logmessages. Do not use this function in the server environment. More...
 
 tpco_setLogIndex
 This function adds an attribute entry (key and value) to the index of the specified log channel. More...
 
 tpco_udpDumpLogFile
 This function exports a logfile from the logserver. The tpco_udpDumpLogFile function works only in the BGS environment. For an external usage, use the TPRPC call ::LOGSRV::dumpLogFile. More...
 
 tpco_udpReadAttachment
 This function reads a logfile attachment. More...
 
 tpco_udpWriteAttachment
 This function writes a logfile attachment. More...
 
 tpco_udpWriteRemoteAttachment2
 This function writes a logfile attachment from remote. More...
 
 tpwrite
 This function writes a logmessage to the BGS log server. More...
 
 writeLogMessageWithAttachment strLogChannel strLogLine strLinkName strAttachmentData ?strAttachmentMType? ?strMessageType? ?strAttachmentName? ?strAttachmentSecurityContext? ?strMessageSecurityContext?
 Creates an attachment on the log server (BGS) and adds the link to the specified log line. If a security context for the attachment is specfied, the attachement is created with the assigned security context. If a security context for the log message is specified, the message is created with the assigned security context. More...
 

Detailed Description

Function Documentation

◆ createLogChannel()

LogTools::createLogChannel   LogChannel  

This functions initializes the search index for the specified log channel.

Remarks
Required to define the security context of a log channel before the first log message is written to the log channel.
Parameters
LogChannelthe log channel path
Returns
nothing on success or throws an exception

Sample code sequence including definition of security context

1 set LogChannelPath "/tmp/test.log"
2 ::LogTools::createLogChannel $LogChannelPath
3 ::LogTools::setSecurityContext4LogChannel $LogChannelPath STRICTLYCONFIDENTIAL
4 tpwrite -logchannel $LogChannelPath -mtype INTERN "My test Message"

◆ getBinLogFile()

LogTools::getBinLogFile   logchannel target zip  

This function downloads a binary logfile from the BGS server and stores this in the local filesystem.

Parameters
logchannelthe relative path to the logfile
targetthe file name in the local file system
zip(optional) "zip" compress the download
Returns
0=ok, 1=error

download the logfile /sys/nihil/BGS_20120717-043049/tpbgs64_netd.log and store the compressed content in the file test.log.

1 ::LogTools::getBinLogFile /sys/nihil/BGS_20120717-043049/tpbgs64_netd.log test.log zip

◆ setSecurityContext4LogChannel()

LogTools::setSecurityContext4LogChannel   LogChannel SecurityContext  

Sets the security context of a given logchannel.

Parameters
LogChannelthe logchannel path
SecurityContextthe new security context of the log channel, which can be:
  • UNRESTRICTED
  • RESTRICTED
  • CONFIDENTIAL
  • STRICTLYCONFIDENTIAL
Precondition
Make sure that the log index for the logchannel is already created by the system or via the LogTools::createLogChannel function.
Returns
nothing on success or throws an exception

It is only possible to increase the security context, that means setting the SecurityContext to UNRESTRICTED has no effect, if the log channel is already assigned to the security context STRICTLYCONFIDENTIAL.

1 ::LogTools::setSecurityContext4LogChannel /tmp/test.log STRICTLYCONFIDENTIAL

◆ storeBinLogFile()

LogTools::storeBinLogFile   src logchannel  

This function upload a binary logfile to the BGS server.

Parameters
srcthe file name in the local file system
logchannelthe relative path to the logfile
Returns
0=ok, 1=error

uploads the logfile test.log to the BGS server (/tmp/test.log).

1 ::LogTools::storeBinLogFile test.log /tmp/test.log

◆ testLogPattern()

LogTools::testLogPattern   logchannel pattern  

Test the last line of a logfile for a keyword.

Deprecated:
Parameters
logchannelthe relative path to the logfile
patternTCL string pattern (keyword)
Returns
1=exists 0=does not exist

Test, if the last logile in the logfile /sys/nihil/BGS_20120717-043049/tpbgs64_netd.log contains the pattern "*TEST*"

1 ::LogTools::testLogPattern /sys/nihil/BGS_20120717-043049/tpbgs64_netd.log *TEST*

◆ tpco_getListOfValues()

tpco_getListOfValues

This function returns all occurring values for a certain key (without duplicates) as well as the number of absolute occurrences for each found value.

Parameters
keyAttribute key for which all existing values and number of occurrences should be returned.
rrangeThe result range of the corresponding searchresult (default [list 0 9])
rsortdsort direction of the result list. The sortkey is absolute number of occurrences.
loglistprevious result of any search to be searched, if the loglist is not provided, all index entries will be searched.
Returns
TCL-list {<total # of values>

<occurrences>

<occurrences> ..}

1  tpco_getListOfValues -key transaction -rsortd decreasing
2 
3 output:
4 9 CHANGE_HID 278 MODIFY 278 DELETE 278 EXPORT 278 CHANGE 278 REMOVE 278 KILL 278 READ 277 WRITE 277

◆ tpco_getLogIndex()

tpco_getLogIndex

This function returns the key attribute list of a specified log channel, matching the given patterns for key and value.

Parameters
logchannelstring of the log channel
keypatternpattern to match the key of the attribute as string
valuepatternpattern to match the value of the attribute
usesctxdefine the security context of this call, should be higher than the used security context in the log index
  • UNRESTRICTED
  • RESTRICTED
  • CONFIDENTIAL
  • STRICTLYCONFIDENTIAL
Returns
Tcl Dict or {ERROR MESSAGE}
<KEY>
1 foreach {key value} [tpco_getLogIndex -logchannel /tmp/test/default.log -keypattern * -valuepattern *] {puts "$key => $value"}
2 
3 output:
4 ITEMID => 47110815
5 LOGNAME => /tmp/test/default.log
6 CTIME => 1422864704
7 MTIME => 1422864704

◆ tpco_removeLogIndex()

tpco_removeLogIndex

This function removes an attribute entry from the specified log channel.

Parameters
logchannelstring of the log channel
keythe name for the key
Returns
none

◆ tpco_searchGlobLogIndex()

tpco_searchGlobLogIndex

This function simply searches globally for all terms defined in searchlist within the whole log index. It returns a list of matching log index entries.

Parameters
searchlistList of search terms as strings
rrangeThe result range of the corresponding searchresult (default [list 0 9])
rsortsort key and direction for the searchresult. (default CTIME decreasing)
linkthe logical link between the search patterns (default OR)
casedefines whether this search should be case-sensitive or not
true: to search case-sensitive
false: to ignore any case (DEFAULT)
keylovAttribute key for which all existing values and number of occurrences should be returned.
klovrangeThe result range of the corresponding result for keylov (default [list 0 9])
Returns
TCL-list {<total # of hits> <log channel>=""> <log channel>=""> ...} - without KeyOfValue if the param keylov is set then the last element of the result list is the result of the KeyOfValue function TCL-list {<total # of hits> <log channel>=""> <log channel>=""> ... {<key of value result}} - with KeyOfValue
1 foreach index [tpco_searchGlobLogIndex -searchlist [list BOM] -rrange [list 0 5] -rsort [list CTIME decreasing] -case true -link OR] {puts $index}
2 
3 output:
4 120
5 /trans/20150126/023454510266_QHT!9XhaaaNQCAAAAAAAAAAAAA_DIR.log
6 /trans/20150126/082460978229_QHT\]9XhweweNQCAAAAAAAAAAAAA_DIR.log
7 /trans/20150126/119506296832_QHT,9XhWWNQCAAAAAAAAAAAAA_DIR.log
8 /trans/20150126/086874764172_QHTV9XhFGNQCAAAAAAAAAAAAA_DIR.log
9 /trans/20150126/077811290638_QHT^9XhndnsdNQCAAAAAAAAAAAAA_DIR.log

◆ tpco_searchLogIndex()

tpco_searchLogIndex

This function can search for several specific keys and values at once. It returns a list of matching log index entries, which can be used to get the corresponding log files. If the key is defined as “*” and the value is defined as “*”, all entries are returned.

Parameters
patterntcl dictionary containing any number of key-value-pairs, where each value con-sists of a list, where the first entry represents the submitted data type and the second value contains the searched value pattern.
e.g. [ <key1> {<type1> <valuepattern1>} <key2> {<type2> <valuepattern2>} …]
key pattern to match the key of an attribute as string
type data type of the valuepattern (STR - string, STRLIST – a list of strings, UINTRNAGE – a range of interger values e.g. [list 4711 9192])
valuepattern: pattern to be searched for in the according key, needs to match the re-quirements of the previously defined data type.
rrangeThe result range of the corresponding searchresult (default [list 0 9])
rsortsort key and direction for the searchresult. (default CTIME decreasing)
linkthe logical link between the search patterns (default OR)
casedefines whether this search should be case-sensitive or no
true: to search case-sensitive
false: to ignore any case (DEFAULT)
keylovAttribute key for which all existing values and number of occurrences should be returned.
klovrangeThe result range of the corresponding result for keylov (default [list 0 9])
Returns
TCL-list {<total # of hits> <log channel>=""> <log channel>=""> ...} - without KeyOfValue if the param keylov is set then the last element of the result list is the result of the KeyOfValue function TCL-list {<total # of hits> <log channel>=""> <log channel>=""> ... {<key of="" value="" result>="">}} - with KeyOfValue
1 tpco_searchLogIndex -pattern [list [list ITEMID [list STR *1108*]] [list * [list STR BOM]]]
2 
3 output:
4 121 /tmp/test/default.log /trans/20150126/069677646163_QHTK9XhwdnsdNQCAAAAAAAAAAAAA_DIR.log {/trans/20150126/074506290720_QHT\"9XhASNQCAAAAAAAAAAAAA_DIR.log} /trans/20150126/038192107819_QHT69XhRRRNQCAAAAAAAAAAAAA_DIR.log /trans/20150126/102872432881_QHTM9XhndnsdNQCAAAAAAAAAAAAA_DIR.log {/trans/20150126/065757690448_QHT\"9XhFGNQCAAAAAAAAAAAAA_DIR.log} /trans/20150126/025663203363_QHTM9XhWWNQCAAAAAAAAAAAAA_DIR.log /trans/20150126/117993730389_QHT19XhweweNQCAAAAAAAAAAAAA_DIR.log /trans/20150126/106310332126_QHTO9XhaaaNQCAAAAAAAAAAAAA_DIR.log

◆ tpco_setdlogchannel()

tpco_setdlogchannel

This function sets the default logchannel for logmessages. Do not use this function in the server environment.

Parameters
logchannelthe default logchannel
Returns
nothing
1 tpco_setdlogchannel /tmp/xyz/thenewdefault.log

◆ tpco_setLogIndex()

tpco_setLogIndex

This function adds an attribute entry (key and value) to the index of the specified log channel.

Parameters
logchannelstring of the log channel
keythe name for the key
valuevalue for the previously defined key to be set
modeoverwrite: The data will be overwritten (default setting)
exclusive: if this entry has been defined before nothing will happen, else it will be exclusively set once to the index
append: the data will be appended, regardless if the entry does already exist or not
Returns
none
1 tpco_setLogIndex -logchannel /tmp/test/default.log -key ITEMID -value 47110815 -mode overwrite

◆ tpco_udpDumpLogFile()

tpco_udpDumpLogFile

This function exports a logfile from the logserver. The tpco_udpDumpLogFile function works only in the BGS environment. For an external usage, use the TPRPC call ::LOGSRV::dumpLogFile.

Parameters
outtypestring (logfile translate to a UTF-8 string)
html (logfile translate to a HTML string)
native (internal use only)
sizethe last n-lines of the logfile. -1 = all lines
filenamethe name and path of the logfile
Returns
the logfile returns the logfile as a TCL list. 1 = cannot export logfile
1 {
2  {mode {id subid} stacklevel ctime time-usec INTERN INTERN thid-hw thid-lw pid-hw pid-lw hostname client client-ip message}
3  {mode {id subid} stacklevel ctime time-usec INTERN INTERN thid-hw thid-lw pid-hw pid-lw hostname client client-ip message}
4  ...
5 }
6  mode: 0=DEBUG 1=ERROR 2=WARNING 3=NODE 4=OK 5=INTERN
7  id, subid message id and subid (multi line support)
8  ctime, time-usec message time ctime,time-usec

Examples:

Dump the last 10 lines of a logfile in the BGS environment as text output:

1 puts [tpco_udpDumpLogFile text 10 /sys/nihil/BGS_20120705-133114/tpbgs.log]

Dump the last 10 lines of a logfile via the network as text output:

1 ::ProxyGen::createClientFor "BGS" 60 0 0 ::LOGSRV::dumpLogFile ::dumplog
2 set dump [::dumplog text 10 /sys/nihil/BGS_20120705-133114/tpbgs.log]
3 foreach logline $dump {
4  puts $logline
5 }
6 
7  output:
8  0 {77 0} 0 50016da4 c07bb 0 0 5cf73740 7f6d 165c 0 {nihil} {tpbgs} {::ffff:127.0.0.1} {::tpcore::threadcreate :: StackSize=524288 TF=1}
9  5 {78 0} 0 50016da4 c7acc 0 0 31b78700 7f6d 165c 0 {nihil} {tpbgs} {::ffff:127.0.0.1} {set RCWD=/home/joerg/work/TR1480/tp_core_Linux_x86_64_debug}
10  5 {79 0} 0 50016da4 d6dcf 0 0 33afa700 7f6d 165c 0 {nihil} {tpbgs} {::ffff:127.0.0.1} {:: INIT BATCH SERVER API }
11  5 {7a 0} 0 50016da4 db48c 0 0 33afa700 7f6d 165c 0 {nihil} {tpbgs} {::ffff:127.0.0.1} {sys_01000000.sd :: TPDS FINISH}
12  5 {7b 0} 0 50016da4 f1143 0 0 31b78700 7f6d 165c 0 {nihil} {tpbgs} {::ffff:127.0.0.1} {:: INIT BATCH SERVER API }
13  5 {7c 0} 0 50016da4 f3f43 0 0 31b78700 7f6d 165c 0 {nihil} {tpbgs} {::ffff:127.0.0.1} {sys_01000000.sd :: TPDS FINISH}
14  3 {7e 0} 0 50016da5 75a67 0 0 5cf73740 7f6d 165c 0 {nihil} {tpbgs} {::ffff:127.0.0.1} {USE CODE OPTIMATION PATH :: INTEL CC SSE4 CPUCODE=45 FEATURES=MMX SSE SSE2 SSE3 SSSE3 SSE41 SSE42 }
15  5 {7f 0} 0 50016dc2 a72ab 0 0 3282c700 7f6d 165c 0 {nihil} {tpbgs} {::ffff:127.0.0.1} {tpco_udpCleanLogStorage :: START LOGFILE - CLEANER}
16  5 {80 0} 0 50016dc4 5ebe1 0 0 3282c700 7f6d 165c 0 {nihil} {tpbgs} {::ffff:127.0.0.1} {tpco_udpCheckLogFile :: REMOVE DIRECTORY=/home/joerg/work/TR1480/tp_core_Linux_x86_64_debug/var/log/stdio}
17  5 {81 0} 0 50016dc4 a81b0 0 0 3282c700 7f6d 165c 0 {nihil} {tpbgs} {::ffff:127.0.0.1} {tpco_udpCleanLogStorage :: FINISH LOGFILE - CLEANER}
18  3 {83 0} 0 50016ddf c6d98 0 0 3abff700 7f6d 165c 0 {nihil} {tpbgs} {::ffff:127.0.0.1} {tpco_connhistMonitor :: INIT CONNECTION HISTORY DEPTH=1024}

◆ tpco_udpReadAttachment()

tpco_udpReadAttachment

This function reads a logfile attachment.

tpco_udpReadAttachment works only in the BGS environment. For external usage, use the ::LOGSRV::readAttachment function.

Parameters
idthe attachment ID
Returns
a TCL list {SUCCESS {MTYPE NAME} DATA} or {ERROR MESSAGE}
1 ::ProxyGen::createClientFor "BGS" 10 0 0 ::LOGSRV::readAttachment ::_readattachment
2 puts [::_readattachment 50055204000000A3]
3 
4 output:
5 SUCCESS {text/xml XML-TEST} {<testtag>hello attachment</testtag>} XML-TEST} {<testtag>hello attachment</testtag>}

◆ tpco_udpWriteAttachment()

tpco_udpWriteAttachment

This function writes a logfile attachment.

tpco_udpWriteAttachment works only in the BGS environment. For external usage, use the tpco_udpWriteRemoteAttachment2 function. The download URL for the attachment is: http(s)://<bgs-server>:<port>/dcx/attach?<attachment-id>. The returned attachment ID can be used to create an HTTP link using TPHAP::setAttaLink.

Parameters
namename of the attachment
mtypeMIME type of the attachment
datacontent of the attachment
sctx(optional) security context of the attachment, which can be:
  • UNRESTRICTED
  • RESTRICTED
  • CONFIDENTIAL
  • STRICTLYCONFIDENTIAL
Returns
a TCL list with either "SUCCESS" and the ID of the attachment or "ERROR" and the detailed error message.

◆ tpco_udpWriteRemoteAttachment2()

tpco_udpWriteRemoteAttachment2

This function writes a logfile attachment from remote.

The download URL for the attachment is: http(s)://<bgs-server>:<port>/dcx/attach?<attachment-id>. The returned attachment ID can be used to create an HTTP link using TPHAP::setAttaLink.

Parameters
mtypeMIME type of the attachment
namename of the attachment
datacontent of the attachment
sctx(optional) security context of the attachment, which can be:
  • UNRESTRICTED
  • RESTRICTED
  • CONFIDENTIAL
  • STRICTLYCONFIDENTIAL
Returns
the ID of the attachment in case of success or a TCL list with "ERROR" and the detailed error message in case of failure.
1 set xml "<testtag>hello attachment</testtag>"
2 puts [tpco_udpWriteRemoteAttachment2 "text/xml" "XML-TEST" $xml]
3 
4 output:
5 50055204000000A3

◆ tpwrite()

tpwrite

This function writes a logmessage to the BGS log server.

Parameters
logmessagethe logmessage (max. size of the logmessage is 32 KByte)
-logchannel(optional) logchannel the message is written to. The default logchannel can be defined using tpco_setdlogchannel. The logchannel is a relative path to the logroot.
-stacklevel(optional) indentation of the logmessage, defined by a number between 0 (default) and 63.
-mtype(optional) the type of message (DEBUG is the default). Types are indicated by the color of log lines:
  • DEBUG black
  • ERROR red
  • WARNING yellow/orange
  • INTERN grey
  • NOTE blue - use this for important messages
  • OK green
-sctx(optional) security context of this message, which can be
  • UNRESTRICTED
  • RESTRICTED
  • CONFIDENTIAL
  • STRICTLYCONFIDENTIAL
The default security context is UNRESTRICTED.
Returns
nothing - tpwrite works asynchronously and does not provide any feedback

Examples:

Writing a logmessage to the default logchannel

1 tpwrite "Hello World"

Writing an error logmessage to the default logchannel

1 tpwrite -mtype ERROR "Hello World"

Writing a logmessage of type "NOTE" to the logchannel /tmp/my_user_logchannel.log

1 tpwrite -logchannel /tmp/my_user_logchannel.log -mtype NOTE "Hello World"

Writing a warning logmessage to the logchannel /tmp/my_user_logchannel.log with security context RESTRICTED

1 tpwrite -logchannel /tmp/my_user_logchannel.log -mtype WARNING "Hello World" -sctx RESTRICTED

◆ writeLogMessageWithAttachment()

LogTools::writeLogMessageWithAttachment   strLogChannel strLogLine strLinkName strAttachmentData ?strAttachmentMType? ?strMessageType? ?strAttachmentName? ?strAttachmentSecurityContext? ?strMessageSecurityContext?  

Creates an attachment on the log server (BGS) and adds the link to the specified log line. If a security context for the attachment is specfied, the attachement is created with the assigned security context. If a security context for the log message is specified, the message is created with the assigned security context.

Parameters
strLogChannelDefines the logchannel in the log server
strLogLineMessage in the logchannel where the attachment will be added as a link
strLinkNameThe name of the link
strAttachmentDataThe content/payload of the attachment
strAttachmentMType(optional) Mime type of the attachment (default text/xml)
strMessageType(optional) Message type (default DEBUG). Types are indicated by the color of log lines:
  • DEBUG black
  • ERROR red
  • WARNING yellow/orange
  • INTERN grey
  • NOTE blue
  • OK green
strAttachmentName(optional) The name of the attachment (default Attachment_timestamp + valid file extension for text/plain (.txt) and text/xml (.xml))
strAttachmentSecurityContext(optional) Security context of the specified attachment data (default is no security context)
  • UNRESTRICTED
  • RESTRICTED
  • CONFIDENTIAL
  • STRICTLYCONFIDENTIAL
strMessageSecurityContext(optional) Security context of the specified strLogLine (log message) parameter (default is no security context)
  • UNRESTRICTED
  • RESTRICTED
  • CONFIDENTIAL
  • STRICTLYCONFIDENTIAL