0001 TM_MIB(5)
0002 =========
0003 :doctype: manpage
0004
0005 NAME
0006 ----
0007 tm_mib - Transaction Manager Management Information Base
0008
0009
0010 SYNOPSIS
0011 --------
0012
0013 Management classes:
0014
0015 - *T_CLIENT* - Client process
0016
0017 - *T_DOMAIN* - Domain
0018
0019 - *T_MACHINE* - Machines in domain
0020
0021 - *T_QUEUE* - IPC Queues
0022
0023 - *T_SERVER* - XATMI server processes
0024
0025 - *T_SERVICE* - XATMI service definitions
0026
0027 - *T_SVCGRP* - XATMI service instances
0028
0029 - *T_BRCON* - tpbridge connection information
0030
0031 - *T_USERDATA* - User data class, collected from user service by Enduro/X EE AgentX.
0032
0033
0034 DESCRIPTION
0035 -----------
0036 This is management information interface for Enduro/X. Currently only information
0037 reading is available, setting or changing system characteristics via this interface
0038 is not possible. Basically TM MIB interface in GET mode is designed, so that
0039 user application can call in standard way ".TMIB" service with requesting
0040 the information for particular object. These object types are encoded as classes.
0041 Thus user requests information about some class, and TMIB service provided
0042 by *tpadmsv(8)* will respond with objects found in system for particular class.
0043
0044 The information fetching is performed with standard *tpcall(3)* service invocations.
0045 Request and response is encoded in UBF buffer format. At request certain fields
0046 are filled (indicating the class and operation), at response the error fields
0047 are filled, object information, number of objects found and number of objects
0048 fetched. For each request cursor is open at particular *tpadmsv*, if objects
0049 fetched are less than found, then cursor_id with GETNEXT operation code shall be
0050 sent to .TMIB, to receive the next portion of data. When all data is fetched, the
0051 cursor is deleted in particular process. Cursor is valid for configured period of
0052 time, which is configured for *tpadmsv*. The page size also is configured in *tpadmsv*
0053 server configuration parameters.
0054
0055 REQUEST BUFFERS
0056 ---------------
0057
0058 To initiate request/open cursor for fetching particular class of information,
0059 following UBF fields shall be filled (defined in tpadm.h/Excompat.h):
0060
0061 - *TA_OPERATION*: Currently supported modes are only *GET* and *GETNEXT*.
0062
0063 - *TA_CLASS*: Shall be set to one of the supported class which is "T_CLIENT",
0064 "T_DOMAIN", "T_MACHINE", "T_QUEUE", "T_SERVER", "T_SERVICE" or "T_SVCGRP".
0065
0066 - *TA_CURSOR*: In case of *GETNEXT* field must be present in order to fetch next
0067 page of the information. The *TA_CURSOR* value must be set from *GET* response
0068 same field *TA_CURSOR*.
0069
0070 The filled UBF buffer must be sent to *.TMIB* service.
0071
0072
0073 RESPONSE STATUS
0074 ---------------
0075 General status information is encoded in following fields UBF fields:
0076
0077 - *TA_ERROR*: Error code, or *0* for success. See section bellow for detailed
0078 error codes.
0079
0080 - *TA_STATUS*: Status message, *OK* in case of success.
0081
0082 - *TA_BADFLD*: Complementary problematic fields ID, in case if error associated
0083 with request data.
0084
0085 If requests succeeds, then data paging information is encoded in following fields:
0086
0087 - *TA_OCCURS*: Number of objects loaded in response.
0088
0089 - *TA_MORE*: Number of objects left for fetching in other pages. I.e. if having
0090 greater than *0*, then *TA_CURSOR* shall be copied to UBF buffer requesting
0091 *GETNEXT* command which is sent to same *.TMIB* service.
0092
0093
0094 TA_ERROR error codes
0095 --------------------
0096 List of error codes which .TMIB interface returns is:
0097
0098 - *-3* (*TAEINVAL*): Invalid fields passed to service. For example invalid
0099 cursor format. Problematic field ID is returned in *TA_BADFLD* field.
0100
0101 - *-9* (*TAEREQUIRED*): Field is required in request, but not present in UBF
0102 buffer. The field ID is returned in *TA_BADFLD*.
0103
0104 - *-10* (*TAESUPPORT*): Operation or class is not supported. Field which encoded
0105 the identifier is set in *TA_BADFLD*.
0106
0107 - *-11* (*TAESYSTEM*): System failure occurred during collection of information
0108 or setting the fields (memory error). See Enduro/X logs for more details.
0109
0110 - *-13* (*TAELIMIT*): Number of open cursors limit reached. Limits is configured
0111 in *tpadmsv(8)* configuration. Basically this means that some problem exists i.e.
0112 requesters have made several requests for information in short period of time
0113 without fetching cursors till the end.
0114
0115
0116 T_CLIENT CLASS
0117 --------------
0118 This class returns information about client processes found in the system. Client
0119 processes are gathered from system in two different ways:
0120
0121 1. XATMI client information is read and decoded from open XATMI queue names.
0122
0123 2. Client information (including XATMI and non XATMI/generic process) is provided
0124 by *cpmsrv(8)* shared memory block.
0125
0126 In case if process is started by *cpmsrv* client process monitor and it operates
0127 as XATMI client, the information is merged, so that identifier of process is
0128 copied from shared memroy (tag/subsection) rather than queue id.
0129
0130 Object fields returned for *T_CLIENT* class are following:
0131
0132 - Field *TA_LMID* (string..30): Cluster node ID on which client process runs. Format
0133 is number 0..255.
0134
0135 - Field *TA_CLIENTID* (string..128): Client process ID. *This is object key*
0136 Identifier consists of XATMI client queue, or if process is standard from Client
0137 Process Monitor (cpmsrv), then client identifier is built as
0138 *<Cluster Node Id>/<CPM Tag>/<CPM Sub Section>*. The benefit of CPM tag id is that
0139 this can be used for monitoring as there are no dynamic data in the identifier. In
0140 opposite of queue identifier, which contains the process PID.
0141 For example "/dom2,clt,reply,atmiclt68,28765,3". In case if for CPM process XATMI
0142 queue exists, then ATMI context ID is extracted from queue and added to via slash
0143 context number to the id string, thus *<Cluster Node Id>/<CPM Tag>/<CPM Sub Section>/<Context ID>*.
0144
0145 - Field *TA_CLTNAME* (string..30): Client process name. This is name of executable,
0146 if process name is longer than 30 chars, then it is cut to 30 chars from the left.
0147
0148 - Field *TA_STATE* (string..15): Client process state. *ACT* - active, *DEA* -
0149 process dead.
0150
0151 - Field *TA_PID* (long): Client process PID.
0152
0153 - Field *TA_CURCONV* (long): Current number of conversations open. For CPM proceses
0154 which are not part of XATMI sub-system, the value is set to *-1*.
0155
0156 - Field *TA_CONTEXTID* (long): Current XATMI client context ID. For non XATMI
0157 processes, the value is set to *-1*.
0158
0159 - Field *TA_CURTIME* (long): Unix epoch time (seconds since January 1, 1970, UTC)
0160 when process was started. This information is available only for CPMSRV booted
0161 processes.
0162
0163 T_DOMAIN CLASS
0164 --------------
0165 Class of these object describes general information about current domain, that
0166 is Enduro/X instance. Information includes such information as number of queues,
0167 servers and services.
0168
0169 Object fields returned for *T_DOMAIN* class are following:
0170
0171 - Field *TA_DOMAINID* (string..30): Cluster node ID.
0172
0173 - Field *TA_STATE* (string..3): Domain state: *ACT* - active, *DEA* - dead.
0174
0175 - Field *TA_CURQUEUES* (long): Number of IPC queues open.
0176
0177 - Field *TA_CURSERVERS* (long): Current number of XATMI servers running.
0178
0179 - Field *TA_CURSERVICES* (long): Current number of services available in shared mem.
0180
0181 *SNMP version notes:*
0182
0183
0184 T_MACHINE CLASS
0185 ---------------
0186 Objects from this class describes current machine and linked machines for the
0187 application cluster. The information about other machines are gathered from
0188 the *tpbridge(8)* processes.
0189
0190 Object fields returned for *T_MACHINE* class are following:
0191
0192 - Field *TA_LMID* (string..30): Cluster node ID.
0193
0194 - Field *TA_CURACCESSERS* (long): Number of XATMI clients and servers present
0195 on particular cluster node. Information is available only for current node. No
0196 information is present from remote machines, and for them *-1* is returned.
0197
0198 - Filed *TA_CURCONV* (long): Number of XATMI conversational sessions open. Information
0199 is only present for local machine, for remote machines *-1* is returned.
0200
0201 - Filed *TA_STATE* (string..3): Cluster node state. *ACT* - active, *INA* -
0202 tpbridge connector is not running, *PEN* - tpbridge connector is running, but
0203 connection is not established yet.
0204
0205
0206 T_QUEUE CLASS
0207 -------------
0208 These objects describe the IPC queues open in the system. Note as Enduro/X is
0209 capable of working with different kind of queues, either Posix on System V, the
0210 output might be different. But basically all queues within Enduro/X are represented
0211 as strings. For System V queues queue id is returned too.
0212
0213 Object fields returned for *T_QUEUE* class are following:
0214
0215 - Field *TA_LMID* (string..30): Cluster node ID.
0216
0217 - Field *TA_RQADDR* (string..128): Queue name. For Posix Queues, this is queue
0218 name. For other approaches, this is Enduro/X representation of the queue.
0219 *This is key of object*.
0220
0221 - Field *TA_STATE* (string..3): Queue state. *ACT* - active.
0222
0223 - Field *TA_NQUEUED* (long): Number of messages currently enqueued.
0224
0225 - Field *TA_RQID* (long): System V msqid, as from ipcs -q output.
0226
0227 T_SERVER CLASS
0228 --------------
0229 This class describes XATMI servers currently defined on current cluster node.
0230
0231 Object fields returned for *T_SERVER* class are following:
0232
0233 - Field *TA_LMID* (string..30): Cluster node ID.
0234
0235 - Field *TA_SRVID* (long): Server instance id, as defined in <srvid> tag in
0236 ndrxconfig.xml(5) with min/max settings applied. *This is the key of object*.
0237
0238 - Field *TA_RQADDR* (string..128): Request address queue. Used only in System V
0239 mode.
0240
0241 - Field *TA_STATE* (string..3): *ACT* - Server process is working. *RES* -
0242 Server process is starting. *CLE* - Server process is stopping. *DEA* - Server
0243 process is dead / stopped. *INA* - Not started or normal shutdown of the server.
0244
0245 - Field *TA_TIMERESTART* (long): *ndrxd(8)* sanity cycles from last state change.
0246 Thus if server *DEA*, it will be sanity cycles since *CLE* state change.
0247
0248 - Field *TA_PID* (long): This is Unix process PID. If process is dead, then
0249 pid number is left from last session it was running.
0250
0251 - Field *TA_SERVERNAME* (string..78): This is server name as defined in
0252 "<server>" tag in *ndrxconfig.xml(5)*.
0253
0254 - Field *TA_CLOPT* (string..256): This is actual binary name which is booted
0255 for the server process. The binary name either matches the *TA_SERVERNAME* or
0256 is extracted from "<cmdline>" tag.
0257
0258 - Field *TA_GENERATION* (long): This is number of consecutive restarts performed
0259 of the process. I.e. if processes is in dead stat, then number of attempts was
0260 made to boot it up till the current moment.
0261
0262 T_SERVICE CLASS
0263 ---------------
0264 This class describes the services defined and available in the system,
0265 without dynamic information.
0266
0267 Object fields returned for *T_SERVICE* class are following:
0268
0269 - Field *TA_LMID* (string..30): Cluster node id.
0270
0271 - Field *TA_SERVICENAME* (string..30): Service name as defined in shared memory.
0272 *This is object key*.
0273
0274 - Filed *TA_STATE* (string..3): *ACT* - service is available, *INA* - service
0275 is not available (was advertised, but currently any server is shutdown).
0276
0277
0278 T_SVCGRP CLASS
0279 --------------
0280 This class describes dynamic information currently available about the services
0281 in the cluster system. Information is retrieved as request from *ndrxd(8)* process
0282 about it's visibility and knowledge of the current system setup.
0283
0284
0285 Object fields returned for *T_SVCGRP* class are following:
0286
0287 - Field *TA_LMID* (string..30): Cluster node ID.
0288
0289 - Field *TA_SERVICENAME* (string..30): *This is key of the object (component 2)*
0290 Service name as defined in shared memory.
0291
0292 - Field *TA_SRVGRP* (string..30): *This is key of the object (component 1)*. Format
0293 *<Cluster node id>/Server id* which provides the service.
0294
0295 - Field *TA_STATE* (string..3): *ACT* - service is available.
0296
0297 - Field *TA_SRVID* (long): Server ID which provides the service.
0298
0299 - Field *TA_SVCRNAM* (string..30): Service routine name (function) associated
0300 with service.
0301
0302 - Field *TA_NCOMPLETED* (long): Number of requests completed. Includes succeed
0303 and fail.
0304
0305 - Field *TA_TOTSUCCNUM* (long): Total number of succeed requests processed.
0306
0307 - Field *TA_TOTSFAILNUM* (long): Total number of failed requests processed.
0308
0309 - Field *TA_LASTEXECTIMEUSEC* (long): Number of microseconds spent for last
0310 service call.
0311
0312 - Field *TA_MAXEXECTIMEUSEC* (long): Max microseconds spent for particular
0313 service instance call.
0314
0315 - Field *TA_MINEXECTIMEUSEC* (long): Minimum microseconds spent for particular
0316 service instance call.
0317
0318 T_BRCON CLASS
0319 -------------
0320 This class returns information about active *tpbridge(8)* connections. Cursor
0321 data includes data from all bridge processes present in Enduro/X instance.
0322 Information is provided only from bridges which have established connection.
0323
0324 Object fields returned for *T_BRCON* class are following:
0325
0326 - Field *TA_EX_NODEID* (long): Enduro/X Cluster Node ID.
0327
0328 - Field *TA_SRVID* (long): Bridge Server ID which provides the service.
0329
0330 - Field *TA_EX_REMNODEID* (long): Remote connected Enduro/X Cluster Node ID.
0331
0332 - Field *TA_EX_FD* (long): Connect file descriptor in the bridge process.
0333
0334 - Field *TA_EX_CONMODE* (char): Connection mode *A* - client (active), *P* - server
0335 (passive).
0336
0337 - Field *TA_EX_TIME* (long): Local monotonic clock, seconds.
0338
0339 - Field *TA_EX_LASTSYNC* (long): Number of seconds after the time synchronization
0340 has happened.
0341
0342 - Field *TA_EX_TIMEDIFF* (long): Monotonic clock time difference between us and
0343 remote node (i.e. our time minus remote time). Use for time correction of the bridge messages.
0344
0345 - Field *TA_EX_TIMEDIFFF* (long): Monotonic clock time difference between us and
0346 remote node (i.e. our time minus remote time), milliseconds fraction
0347
0348 - Field *TA_EX_ROUNDTRIP* (long): Time sync message round trip in milliseconds. Present
0349 only if dynamic clock exchange has happened over the connection.
0350
0351 T_USERDATA CLASS
0352 ----------------
0353 This class name is used as an interface from Enduro/X SNMP AgentX to the
0354 user service which provides data to be exposed on the SNMP channel.
0355
0356 Object fields returned for *T_USERDATA* class shall be following:
0357
0358 - Field *TA_LMID* (string..30): Cluster node ID.
0359
0360 - Field *TA_EX_UVNAME* (string..112):
0361
0362 - Field *TA_EX_UVTYP* (short): Bitmask indication of the fields returned.
0363 Following constants may be OR'ed, to incidate which fields are used in response.
0364 Entry type codes (bits): *1* (0x0001) - string based data and value
0365 is loaded into *TA_EX_UVSTR*. *2* (0x0002) - data type is int32, and value is loaded into
0366 *TA_EX_UVINT32*. *4* (0x0004) - data type is Gauge32 and value is loaded into *TA_EX_UVG32*.
0367 *8* (0x0008) - data type is Counter64 and value is loaded into *TA_EX_UVC64*. When
0368 returning the results all fields must be filled. The fields which does not
0369 return the value for particular type, must be set to "0" or empty string according
0370 to the spare field data type.
0371
0372 - Field *TA_EX_UVSTR* (string): String value.
0373
0374 - Field *TA_EX_UVINT32* (string): Integer32 value.
0375
0376 - Field *TA_EX_UVG32* (string): Gauge32 value.
0377
0378 - Field *TA_EX_UVC64* (string): Counter64 value.
0379
0380
0381 EXAMPLE SESSION OF INFORMATION FETCHING
0382 ---------------------------------------
0383
0384 The example test is performed with "ud" utility.
0385
0386 *Request (initial)*:
0387 --------------------------------------------------------------------------------
0388
0389 $ ud < test.ud
0390 SENT pkt(1) is :
0391 TA_CLASS T_SERVICE
0392 TA_OPERATION GET
0393
0394 --------------------------------------------------------------------------------
0395
0396 *Response*:
0397 --------------------------------------------------------------------------------
0398
0399 RTN pkt(1) is :
0400 TA_ERROR 0
0401 TA_MORE 8
0402 TA_OCCURS 10
0403 TA_CLASS T_SERVICE
0404 TA_CURSOR .TMIB-1-2660_SC000000001
0405 TA_OPERATION GET
0406 TA_SERVICENAME RETSOMEDATA
0407 TA_SERVICENAME UNIX2
0408 TA_SERVICENAME UNIXINFO
0409 TA_SERVICENAME .TMIB-1-2660
0410 TA_SERVICENAME @CPMSVC
0411 TA_SERVICENAME @TM-1-1-810
0412 TA_SERVICENAME @TPRECOVER
0413 TA_SERVICENAME @TM-1-1-1650
0414 TA_SERVICENAME ECHO
0415 TA_SERVICENAME .TMIB
0416 TA_STATE ACT
0417 TA_STATE ACT
0418 TA_STATE ACT
0419 TA_STATE ACT
0420 TA_STATE ACT
0421 TA_STATE ACT
0422 TA_STATE ACT
0423 TA_STATE ACT
0424 TA_STATE ACT
0425 TA_STATE ACT
0426 TA_STATUS OK
0427
0428 --------------------------------------------------------------------------------
0429
0430 *Request next (initial)*:
0431 --------------------------------------------------------------------------------
0432
0433 $ ud < test.ud
0434 SENT pkt(1) is :
0435 TA_CLASS T_SERVICE
0436 TA_CURSOR .TMIB-1-2660_SC000000001
0437 TA_OPERATION GETNEXT
0438
0439 --------------------------------------------------------------------------------
0440
0441 *Response next (and complete)*:
0442
0443 --------------------------------------------------------------------------------
0444
0445 RTN pkt(1) is :
0446 TA_ERROR 0
0447 TA_MORE 0
0448 TA_OCCURS 8
0449 TA_CLASS T_SERVICE
0450 TA_CURSOR .TMIB-1-2660_SC000000001
0451 TA_OPERATION GETNEXT
0452 TA_SERVICENAME TIMEOUTSV
0453 TA_SERVICENAME @TM-1-1
0454 TA_SERVICENAME TESTSV
0455 TA_SERVICENAME SLEEP20
0456 TA_SERVICENAME @TM-1
0457 TA_SERVICENAME @TPBRIDGE002
0458 TA_SERVICENAME NULLSV
0459 TA_SERVICENAME SOFTTOUT
0460 TA_STATE ACT
0461 TA_STATE ACT
0462 TA_STATE ACT
0463 TA_STATE ACT
0464 TA_STATE ACT
0465 TA_STATE ACT
0466 TA_STATE ACT
0467 TA_STATE ACT
0468 TA_STATUS OK
0469
0470 --------------------------------------------------------------------------------
0471
0472 BUGS
0473 ----
0474 Report bugs to support@mavimax.com
0475
0476 SEE ALSO
0477 --------
0478 *tpadmsv(8)* *cpmsrv(8)* *ndrxd(8)* *xadmin(8)*
0479
0480 COPYING
0481 -------
0482 (C) Mavimax, Ltd
0483
