1.*************************************************************************** 2.* Software Testing Automation Framework (STAF) 3.* (C) Copyright IBM Corp. 2007 4.* 5.* This software is licensed under the Eclipse Public License (EPL) V1.0. 6.**************************************************************************** 7 8.*************************-START-OF-PROLOG-**************************** 9.* 10.* File Name : LifeCycleSrv SCRIPT Version 1.0 11.* Descriptive Name : Software Test Automation Framework LifeCycle Service 12.* Detail: 13.* 14.* This file describes the STAF LifeCycle Service. 15.* 16.**************************-END-OF-PROLOG-***************************** 17:i1.lifecycle service 18:ih1.services 19:i2.LifeCycle service 20:h2 id=lifecyclesrv.LifeCycle Service 21:h3.Description 22The LifeCycle service is one of the internal STAF services. It allows STAF 23service requests to be run when STAFProc starts up or shuts down. 24:p.The LifeCycle service provides the following commands. 25:ul compact. 26:li.REGISTER - Allows you to register a STAF service request to be run either 27when STAFProc starts up or shuts down 28:li.UNREGISTER - Allows you to unregister a STAF service request 29:li.UPDATE - Allows you to update fields in a registration 30:li.LIST - Allows you to list information about the STAF service requests 31that are registered 32:li.QUERY - Allows you to get information about a STAF service 33request that is registered 34:li.TRIGGER - Allows you to submit a single registered STAF service request, 35or to submit all STAF service requests registered to be run when STAFProc 36starts up or shuts down. It is useful for testing the registrations. 37:li.ENABLE - Allows you to enable a STAF service request that is registered 38:li.DISABLE - Allows you to disable a STAF service request that is registered 39:li.&help. 40:eul. 41:p. 42The registrations for the LifeCycle service are persistent. This means 43that if STAF is shutdown and restarted (or if the machine is rebooted), 44the prior registration information for the LifeCycle service will still exist. 45When STAFProc starts, it reads in the existing registration data and executes 46the enabled registered STAF service requests with the "Startup" phase specified. 47When STAFProc is shutdown, it reads in the existing registration data and 48executes the enabled registered STAF service requests with the "Shutdown" phase 49specified. The LifeCycle service's registration data is stored in file 50:xph.{STAF/DataDir}/service/lifecycle/lifecycle.reg:exph.. 51:p. 52The STAF LifeCycle service maintains a STAF machine log where it writes 53information about the STAF service requests that have been registered with 54the LifeCycle service and that it has submitted. When debugging a problem 55with a registration for the LifeCycle service, be sure to check the LifeCycle 56service log to determine the results of STAF service requests submitted by 57the LifeCycle service. See :hdref refid=lifecycleServiceLog. for more 58information on the LifeCycle service log. 59.* 60.*--------------------------------------------------------------------- 61.* 62:ih1.service commands 63:ih2.REGISTER 64:i3.LifeCycle service 65:h3.REGISTER 66Allows you to register STAF service requests to be run either when 67STAFProc starts up or shuts down. 68:p. 69Each STAF service request that is registered will be submitted 70synchronously when STAFProc starts up or shuts down, or is triggered 71via a :xph.TRIGGER:exph. request. This means that if you register 72a STAF service request that never completes (e.g. a :xph.PROCESS START 73WAIT:exph. request without a :xph.TIMEOUT:exph. option for a command 74that never completes, or a :xph.SEM MUTEX REQUEST:exph. request with a 75:xph.TIMEOUT:exph. option for a mutex semaphore that never becomes 76available), then if registered for the :xph.Startup:exph. phase, STAFProc 77will not complete starting up. Or, if registered for the :xph.Shutdown:exph. 78phase, STAFProc will not complete shutting down. 79 80:h4.Syntax 81:xmp. 82REGISTER PHASE <Startup | Shutdown> 83 MACHINE <Machine> SERVICE <Service> REQUEST <Request> 84 [ONCE] [PRIORITY <Priority>] [DESCRIPTION <Description>] 85:exmp. 86:p.:xph.PHASE:exph. specifies when the service request will be submitted. 87Valid values are "Startup" and "Shutdown" (case-insensitive). 88Specifying "Startup" indicates to submit the service request when 89STAFProc starts up. Specifying "Shutdown" indicates to submit the 90service request when STAFProc shuts down. 91&varres. 92:p.:xph.MACHINE:exph. specifies the endpoint for a machine where the 93service request will be submitted. 94:p.:xph.SERVICE:exph. specifies the name of the STAF service to which 95a request will be submitted. 96:p.:xph.REQUEST:exph. specifies the request to be submitted to the 97specified service. 98:p.:xph.ONCE:exph. specifies that the STAF service request should only be 99executed once. After the STAF service request has been submitted at Startup or 100Shutdown (depending on the specified phase), the ID for this request will 101be unregistered. 102:p.:xph.PRIORITY:exph. specifies the priority of the registration which is 103used in determining the order in which the registration will be submitted 104(if there is more than one registration) when STAFProc starts up or shuts 105down. It must be a number from 1 to 99. The default is 50. 106Registrations with priority 1 will be submitted first, followed by 107registrations with priority 2, and so on. 108Registrations with the same priority will be submitted in order by 109registration ID. 110&varres. 111:p.:xph.DESCRIPTION:exph. specifies a description of the registration. 112It is for informational purposes only and is optional. 113 114:h4.Security 115:p.&seclvl. 5. 116 117:h4.Return Codes 118:p.All return codes are documented in :hdref refid=retcode.. 119 120:h4.Results 121:p.If successful, the result buffer will contain the registration ID. 122 123:h4.Examples 124:ul. 125:li.:hp2.Goal::ehp2. Register to start a process that runs command 126"C:/tests/TestA.exe" on machine client1.company.com whenever STAFProc 127starts up and specify priority 25 for the registration. 128:p.:hp2.Syntax::ehp2. 129:p.:xph.REGISTER PHASE Startup MACHINE client1.company.com SERVICE Process 130REQUEST "START SHELL COMMAND C:/tests/TestA.exe" DESCRIPTION "Start TestA":exph. 131:p. 132:li.:hp2.Goal::ehp2. Register to run STAX job /test/TestA.xml on machine 133server1 whenever STAFProc starts up. Pass the STAX job's main function a 134Python map of arguments as follows: {'testMachine': 'client1', 'serverMach': 'server1'} 135:p.:hp2.Syntax::ehp2. 136:p.:xph.REGISTER PHASE Startup MACHINE server1 SERVICE STAX REQUEST 137"EXECUTE FILE /tests/TestA.xml ARGS \"{'testMach': 'client1', 138'serverMach': 'server1'}\"":exph. 139:p. 140:li.:hp2.Goal::ehp2. Register to start a process that runs command 141"C:/tests/TestB.exe" on the local machine whenever STAFProc is shut down and 142give it description "Start TestB". 143:p.:hp2.Syntax::ehp2. 144:p.:xph.REGISTER PHASE Shutdown MACHINE local SERVICE Process REQUEST 145"START SHELL COMMAND C:/tests/TestB.exe" DESCRIPTION "Start TestB":exph. 146:p. 147:li.:hp2.Goal::ehp2. Register to send a "STAF Startup" type message to the 148queue of a handle named MyTestHandle on machine server1 the next time 149STAFProc starts up (and then unregister this ID so the message is only sent 150once). 151:p.:hp2.Syntax::ehp2. 152:p.:xph.REGISTER PHASE Startup MACHINE server1 SERVICE QUEUE REQUEST 153"QUEUE NAME MyTestHandle TYPE &colon.12&colon.STAF Startup MESSAGE &colon.0&colon." ONCE:exph. 154:eul. 155.* 156.*--------------------------------------------------------------------- 157.* 158:ih1.service commands 159:ih2.UNREGISTER 160:i3.LifeCycle service 161:h3.UNREGISTER 162Allows you to unregister STAF service requests with the LifeCycle service. 163 164:h4.Syntax 165:xmp. 166UNREGISTER ID <Registration ID> 167:exmp. 168:p.:xph.ID:exph. specifies the registration ID of the STAF service request 169to be unregistered. 170 171:h4.Security 172:p.&seclvl. 5. 173 174:h4.Return Codes 175:p.All return codes are documented in :hdref refid=retcode.. 176 177:h4.Results 178:p.If successful, the result buffer will be empty. 179 180:h4.Examples 181:ul. 182:li.:hp2.Goal::ehp2. Unregister the service request with registration ID 2. 183:p.:hp2.Syntax::ehp2. 184:p.:xph.UNREGISTER ID 2:exph. 185:eul. 186.* 187.*--------------------------------------------------------------------- 188.* 189:ih1.service commands 190:ih2.UPDATE 191:i3.LifeCycle service 192:h3.UPDATE 193Allows you to update one or more fields for a registration. 194 195:h4.Syntax 196:xmp. 197UPDATE ID <Registration ID> [PRIORITY <Priority>] [ONCE <True | False>] 198 [MACHINE <Machine>] [SERVICE <Service>] [REQUEST <Request>] 199 [PHASE <Startup | Shutdown>] [DESCRIPTION <Description>] 200:exmp. 201:p.:xph.ID:exph. specifies the registration ID of the STAF service request 202to be updated. 203:p.:xph.PRIORITY:exph. specifies the priority of the registration which is 204used in determining the order in which the registration will be submitted 205(if there is more than one registration) when STAFProc starts up or shuts 206down. It must be a number from 1 to 99. 207Registrations with priority 1 will be submitted first, followed by 208registrations with priority 2, and so on. 209Registrations with the same priority will be submitted in order by 210registration ID. 211&varres. 212:p.:xph.ONCE:exph. specifies whether the STAF service request should only be 213executed once. Valid values are "True" and "False" (case-insensitive). 214Specifying "True" indicates to submit the STAF service request only once 215which means after the STAF service request has been submitted at Startup or 216Shutdown (depending on the specified phase), this registration will be 217unregistered. Specifying "False" indicates that the STAF service request 218should be submitted each time STAFProc starts up or shuts down (depending 219on the specified phase). 220&varres. 221:p.:xph.MACHINE:exph. specifies the endpoint for a machine where the 222service request will be submitted. 223:p.:xph.SERVICE:exph. specifies the name of the STAF service to which 224a request will be submitted. 225:p.:xph.REQUEST:exph. specifies the request to be submitted to the 226specified service. 227:p.:xph.PHASE:exph. specifies when the service request will be submitted. 228Valid values are "Startup" and "Shutdown" (case-insensitive). 229Specifying "Startup" indicates to submit the service request when 230STAFProc starts up. Specifying "Shutdown" indicates to submit the 231service request when STAFProc shuts down. 232&varres. 233:p.:xph.DESCRIPTION:exph. specifies a description of the registration. 234It is for informational purposes only and is optional. 235 236:h4.Security 237:p.&seclvl. 5. 238 239:h4.Return Codes 240:p.All return codes are documented in :hdref refid=retcode.. 241 242:h4.Results 243:p.If successful, the result buffer will be empty. 244 245:h4.Examples 246:ul. 247:li.:hp2.Goal::ehp2. Update the priority of registration ID 2 to have 248priority 25 and description "Run TestA". 249:p.:hp2.Syntax::ehp2. 250:p.:xph.UPDATE ID 2 PRIORITY 25 DESCRIPTION "Run TestA":exph. 251:eul. 252.* 253.*--------------------------------------------------------------------- 254.* 255:ih1.service commands 256:ih2.LIST 257:i3.LifeCycle service 258:h3.LIST 259Allows you to list the information about the STAF service requests 260registered with the LifeCycle service. The registrations will be 261listed in the order in which they will be submitted, which is by 262phase (Startup registrations first, followed by Shutdown registrations), 263and then in ascending order by priority within the same phase, and then 264in ascending order by registration ID within the same phase/priority. 265 266:h4.Syntax 267:xmp. 268LIST &lbrk.PHASE <Startup | Shutdown>&rbrk. &lbrk.LONG&rbrk. 269:exmp. 270:p.:xph.PHASE:exph. specifies to list only the registrations with a 271matching phase. Valid values for "Startup" and "Shutdown" (case-insensitive). 272&varres. 273:p.:xph.LONG:exph. specifies to include all of the registration information, 274including the description for each registration. 275 276:h4.Security 277:p.&seclvl. 2. 278 279:h4.Return Codes 280:p.All return codes are documented in :hdref refid=retcode.. 281 282:h4.Results 283:p.If successful, the result buffer will contain information 284about the request based on the options specified: 285:ul. 286:li.The result buffer for a :xph.LIST:exph. request without the 287:xph.LONG:exph. option will contain a marshalled :xph.<List> of 288<Map&colon.STAF/Service/LifeCycle/Reg>:exph. representing the matching 289registrations for the LifeCycle service. 290The map is defined as follows: 291:table cols='* * * *'. 292:tcap.Definition of map class STAF/Service/LifeCycle/Reg 293:tnote text='Description'.This map class represents information about 294a registration. 295:thd. 296:c.Key Name 297:c.Display Name 298:c.Type 299:c.Format / Value 300:ethd. 301:row. 302:c.phase 303:c.Phase 304:c.&stringObj. 305:c.'Startup' | 'Shutdown' 306:row. 307:c.priority 308:c.Priority 309.br(P) 310:c.&stringObj. 311:c.'1' - '99' 312:row. 313:c.id 314:c.ID 315:c.&stringObj. 316:c. 317:row. 318:c.state 319:c.State 320:c.&stringObj. 321:c.'Enabled' | 'Disabled' 322:row. 323:c.machine 324:c.Machine 325:c.&stringObj. 326:c. 327:row. 328:c.service 329:c.Service 330:c.&stringObj. 331:c. 332:row. 333:c.request 334:c.Request 335:c.&stringObj. 336:c.Private data will be masked 337:row. 338:c.once 339:c.Once 340:c.&stringObj. 341:c.'True' | 'False' 342:etable. 343:p. 344:li. 345:p.The result buffer for a :xph.LIST:exph. with the :xph.LONG:exph. 346option will contain a marshalled :xph.<List> of 347<Map&colon.STAF/Service/LifeCycle/RegDetails>:exph. representing the 348matching registrations for the LifeCycle service. 349The map is defined as follows: 350:table cols='* * * *'. 351:tcap.Definition of map class STAF/Service/LifeCycle/RegDetails 352:tnote text='Description'.This map class represents detailed 353information about a registration. 354:thd. 355:c.Key Name 356:c.Display Name 357:c.Type 358:c.Format / Value 359:ethd. 360:row. 361:c.phase 362:c.Phase 363:c.&stringObj. 364:c.'Startup' | 'Shutdown' 365:row. 366:c.priority 367:c.Priority 368.br(P) 369:c.&stringObj. 370:c.'1' - '99' 371:row. 372:c.id 373:c.ID 374:c.&stringObj. 375:c. 376:row. 377:c.state 378:c.State 379:c.&stringObj. 380:c.'Enabled' | 'Disabled' 381:row. 382:c.machine 383:c.Machine 384:c.&stringObj. 385:c. 386:row. 387:c.service 388:c.Service 389:c.&stringObj. 390:c. 391:row. 392:c.request 393:c.Request 394:c.&stringObj. 395:c.Private data will be masked 396:row. 397:c.description 398:c.Description 399:c.&stringObj. | &noneObj. 400:c. 401:row. 402:c.once 403:c.Once 404:c.&stringObj. 405:c.'True' | 'False' 406:etable. 407:eul. 408 409:h4.Examples 410:p. 411:ul. 412:li.:hp2.Goal::ehp2. List all the registrations for the LifeCycle service. 413:p.:hp2.Syntax::ehp2. :xph.LIST:exph. 414:p.:hp2.Results::ehp2. If the request is issued from the command line, 415the result, in table format, could look like: 416:xmp keep=12. 417Phase P ID State Machine Service Request Once 418------- -- -- ------- ------- ------- ------------------------------------ ---- 419Startup 25 1 Enabled local PROCESS START SHELL COMMAND C:/tests/TestA.e Fals 420 xe e 421Startup 25 4 Enabled client1 PROCESS START SHELL COMMAND C:/test/TestB.ex Fals 422 e WAIT e 423Startup 40 3 Disable local PROCESS START SHELL COMMAND C:/test/TestC.ex Fals 424 d e WAIT e 425Startup 50 5 Enabled server1 STAX EXECUTE FILE C:/stax/jobA.xml Fals 426 e 427Shutdow 25 2 Enabled local PROCESS START SHELL COMMAND C:/tests/TestTer True 428n m.exe 429Shutdow 50 6 Enabled server1 STAX EXECUTE FILE C:/stax/jobTerm.xml Fals 430n e 431:exmp. 432:p. 433:li. 434:hp2.Goal::ehp2. List the startup registrations for the LifeCycle service. 435:p.:hp2.Syntax::ehp2. :xph.LIST PHASE Startup:exph. 436:p.:hp2.Results::ehp2. If the request is issued from the command line, 437the result, in table format, could look like: 438:xmp keep=8. 439Phase P ID State Machine Service Request Once 440------- -- -- ------- ------- ------- ------------------------------------ ---- 441Startup 25 1 Enabled local PROCESS START SHELL COMMAND C:/tests/TestA.e Fals 442 xe e 443Startup 25 4 Enabled client1 PROCESS START SHELL COMMAND C:/test/TestB.ex Fals 444 e WAIT e 445Startup 40 3 Disable local PROCESS START SHELL COMMAND C:/test/TestC.ex Fals 446 d e WAIT e 447Startup 50 5 Enabled server1 STAX EXECUTE FILE C:/stax/jobA.xml Fals 448 e 449:exmp. 450:p. 451:li. 452:hp2.Goal::ehp2. List the shutdown registrations for the LifeCycle service. 453:p.:hp2.Syntax::ehp2. :xph.LIST PHASE Shutdown:exph. 454:p.:hp2.Results::ehp2. If the request is issued from the command line, 455the result, in table format, could look like: 456:xmp keep=5. 457Phase P ID State Machine Service Request Once 458-------- -- -- ------- ------- ------- ----------------------------------- ---- 459Shutdown 25 2 Enabled local PROCESS START SHELL COMMAND C:/tests/TestTe True 460 rm.exe 461Shutdown 50 6 Enabled server1 STAX EXECUTE FILE C:/stax/jobTerm.xml Fals 462 e 463:exmp. 464:p. 465:li. 466:hp2.Goal::ehp2. List the startup registrations for the LifeCycle service 467in the long format. 468:p.:hp2.Syntax::ehp2. :xph.LIST PHASE Startup LONG:exph. 469:p.:hp2.Results::ehp2. If the request is issued from the command line, 470the result, in table format, could look like: 471:xmp keep=10. 472Phase P ID State Machine Service Request Description Once 473------- -- -- ------- ------- ------- ----------------------- ----------- ----- 474Startup 25 1 Enabled local PROCESS START SHELL COMMAND C:/ Run TestA False 475 tests/TestA.exe 476Startup 25 4 Enabled client1 PROCESS START SHELL COMMAND C:/ Run TestB False 477 test/TestB.exe WAIT 478Startup 40 3 Disable local PROCESS START SHELL COMMAND C:/ Run TestC False 479 d test/TestC.exe WAIT 480Startup 50 5 Enabled server1 STAX EXECUTE FILE C:/stax/jo Run STAX Jo False 481 bA.xml bA 482:exmp. 483:eul. 484.* 485.*--------------------------------------------------------------------- 486.* 487:ih1.service commands 488:ih2.QUERY 489:i3.LifeCycle service 490:h3.QUERY 491Allows you to get information about a STAF service request 492registered with the LifeCycle service. 493 494:h4.Syntax 495:xmp. 496QUERY ID <Registration ID> 497:exmp. 498:p.:xph.ID:exph. specifies the registration ID of the STAF service request 499to be queried. 500&varres. 501 502:h4.Security 503:p.&seclvl. 2. 504 505:h4.Return Codes 506:p.All return codes are documented in :hdref refid=retcode.. 507 508:h4.Results 509:p.If successful, the result buffer will contain a marshalled 510:xph.<Map&colon.STAF/Service/LifeCycle/RegQuery>:exph. representing 511information about the registration. 512The map is defined as follows: 513:table cols='* * * *'. 514:tcap.Definition of map class STAF/Service/LifeCycle/RegQuery 515:tnote text='Description'.This map class represents information about 516a registration. 517:thd. 518:c.Key Name 519:c.Display Name 520:c.Type 521:c.Format / Value 522:ethd. 523:row. 524:c.phase 525:c.Phase 526:c.&stringObj. 527:c.'Startup' | 'Shutdown' 528:row. 529:c.priority 530:c.Priority 531:c.&stringObj. 532:c.'1' - '99' 533:row. 534:c.id 535:c.ID 536:c.&stringObj. 537:c. 538:row. 539:c.state 540:c.State 541:c.&stringObj. 542:c.'Enabled' | 'Disabled' 543:row. 544:c.machine 545:c.Machine 546:c.&stringObj. 547:c. 548:row. 549:c.service 550:c.Service 551:c.&stringObj. 552:c. 553:row. 554:c.request 555:c.Request 556:c.&stringObj. 557:c.Private data will be masked 558:row. 559:c.description 560:c.Description 561:c.&stringObj. | &noneObj. 562:c. 563:row. 564:c.once 565:c.Once 566:c.&stringObj. 567:c.'True' | 'False' 568:etable. 569 570:h4.Examples 571:p. 572:ul. 573:li.:hp2.Goal::ehp2. Query registration ID 5 for the LifeCycle service. 574:p.:hp2.Syntax::ehp2. :xph.QUERY 5:exph. 575:p.:hp2.Results::ehp2. If the request is issued from the command line, 576the result, in default format, could look like: 577:xmp keep=8. 578Phase : Startup 579Priority : 50 580ID : 5 581State : Enabled 582Machine : server1 583Service : STAX 584Request : EXECUTE FILE C:/stax/jobA.xml 585Description: Run STAX JobA 586Once : False 587:exmp. 588:eul. 589.* 590.*--------------------------------------------------------------------- 591.* 592:ih1.service commands 593:ih2.TRIGGER 594:i3.LifeCycle service 595:h3.TRIGGER 596Allows you to submit a single registered STAF service request, or to 597submit all STAF service requests registered to be run at the Startup 598or Shutdown phase. It is useful for testing the registrations without 599requiring that STAFProc be started or shutdown. 600:p. 601Only enabled STAF requests will be submitted by a :xph.TRIGGER PHASE:exph. 602request. A :xph.TRIGGER ID:exph. request will submit enabled and disabled 603STAF requests. Each STAF service request that is triggered will be 604submitted synchronously (e.g. waits for the STAF service request to complete) 605before returning or submitting the next STAF service request if the 606:xph.PHASE:exph. option was specified and there are more STAF service 607requests registered for the specified phase. This means that if you register 608a STAF service request that never completes (e.g. a :xph.PROCESS START:exph. 609request using the :xph.WAIT:exph. option but not the :xph.TIMEOUT:exph. option, 610or a :xph.SEM MUTEX REQUEST:exph. request without a :xph.TIMEOUT:exph. option 611for a mutex semaphore that never becomes available), then the 612:xph.TRIGGER:exph. request will never complete. 613Note that if the submitted STAF service request was registered with the 614ONCE option, triggering the STAF command will not cause the registration 615to be unregistered. 616 617:h4.Syntax 618:xmp. 619TRIGGER <ID <Registration ID> { PHASE <Startup | Shutdown>> CONFIRM 620:exmp. 621:p.:xph.ID:exph. specifies the registration ID of the STAF service request 622to be triggered. 623&varres. 624:p.:xph.PHASE:exph. specifies to trigger all the registrations with 625a matching phase. Valid values are "Startup" and "Shutdown" 626(case-insensitive). 627&varres. 628:p.:xph.CONFIRM:exph. specifies you really want to trigger submitting 629the STAF service requests specified by the matching registration(s). 630 631:h4.Security 632:p.&seclvl. 5. 633 634:h4.Return Codes 635:p.All return codes are documented in :hdref refid=retcode.. 636 637:h4.Results 638:p.If successful, the result buffer will contain information 639about the request based on the options specified: 640:ul. 641:li.The result buffer for a :xph.TRIGGER ID:exph. request will contain 642a marshalled :xph.<Map&colon.STAF/Service/LifeCycle/TriggerId>:exph. 643representing information about the submitted STAF service request. 644The map is defined as follows: 645:table cols='* * * *'. 646:tcap.Definition of map class STAF/Service/LifeCycle/TriggerId 647:tnote text='Description'.This map class represents information about 648the submitted STAF service request. 649:thd. 650:c.Key Name 651:c.Display Name 652:c.Type 653:c.Format / Value 654:ethd. 655:row. 656:c.machine 657:c.Machine 658:c.&stringObj. 659:c. 660:row. 661:c.service 662:c.Service 663:c.&stringObj. 664:c. 665:row. 666:c.request 667:c.Request 668:c.&stringObj. 669:c.Private data will be masked 670:row. 671:c.rc 672:c.RC 673:c.&stringObj. 674:c. 675:row. 676:c.result 677:c.Result 678:c.&stringObj | :xph.<Marshalling Context>:exph.. 679:c. 680:tnote text='Notes'. 681:ol compact. 682:li."RC" contains the return code from submitting the STAF service request. 683:li."Result" contains the result from submitting the STAF service request. 684If the service request returns marshalled data, the "Result" will contain 685a marshalling context representing the result from submitting the STAF 686service request. 687:eol. 688:etnote. 689:etable. 690:p. 691:li.The result buffer for a :xph.TRIGGER PHASE:exph. request will 692contain a marshalled :xph.<List> of 693<Map&colon.STAF/Service/LifeCycle/TriggerIds>:exph. representing 694information about each submitted STAF service request. 695The map is defined as follows: 696:table cols='* * * *'. 697:tcap.Definition of map class STAF/Service/LifeCycle/TriggerIds 698:tnote text='Description'.This map class represents information about 699the submitted STAF service requests. 700:thd. 701:c.Key Name 702:c.Display Name 703:c.Type 704:c.Format / Value 705:ethd. 706:row. 707:c.id 708:c.ID 709:c.&stringObj. 710:c. 711:row. 712:c.machine 713:c.Machine 714:c.&stringObj. 715:c. 716:row. 717:c.service 718:c.Service 719:c.&stringObj. 720:c. 721:row. 722:c.request 723:c.Request 724:c.&stringObj. 725:c.Private data will be masked 726:row. 727:c.rc 728:c.RC 729:c.&stringObj. 730:c. 731:row. 732:c.result 733:c.Result 734:c.&stringObj | :xph.<Marshalling Context>:exph.. 735:c. 736:tnote text='Notes'. 737:ol compact. 738:li."RC" contains the return code from submitting the STAF service request. 739:li."Result" contains the result from submitting the STAF service request. 740If the service request returns marshalled data, the "Result" will contain 741a marshalling context representing the result from submitting the STAF 742service request. 743:eol. 744:etnote. 745:etable. 746:eul. 747 748:h4.Examples 749:p. 750:ul. 751:li.:hp2.Goal::ehp2. Submit the STAF service request specified for 752registration ID 5. 753:p.:hp2.Syntax::ehp2. :xph.TRIGGER ID 5 CONFIRM:exph. 754:p.:hp2.Results::ehp2. If the request is issued from the command line, 755the result, in default format, could look like the following if the 756registration submitted a "EXECUTE FILE C:/stax/jobA.xml" request to the 757STAX service on machine server1: 758:xmp keep=5. 759 Machine: server1 760 Service: STAX 761 Request: EXECUTE FILE C:/stax/jobA.xml 762 RC : 0 763 Result : 4 764:exmp. 765:p. 766:li.:hp2.Goal::ehp2. Submit the STAF service request(s) specified to run 767when STAFProc starts up. 768:p.:hp2.Syntax::ehp2. :xph.TRIGGER PHASE Startup CONFIRM:exph. 769:p.:hp2.Results::ehp2. If the request is issued from the command line, 770the result, in verbose format, could look like the following: 771:xmp keep=9. 772 [ 773 { 774 ID : 1 775 Machine: local 776 Service: PROCESS 777 Request: START SHELL COMMAND C:/tests/TestA.exe 778 RC : 0 779 Result : 58 780 } 781 { 782 ID : 4 783 Machine: client1 784 Service: PROCESS 785 Request: START SHELL COMMAND C:/test/TestB.exe WAIT 786 RC : 0 787 Result : { 788 Return code: 0 789 Key : <None> 790 Files : [ 791 { 792 Return code: 0 793 Data : TestB was successful 794 } 795 ] 796 } 797 } 798 { 799 ID : 5 800 Machine: server1 801 Service: STAX 802 Request: EXECUTE FILE C:/stax/jobA.xml 803 RC : 0 804 Result : 4 805 } 806 ] 807:exmp. 808:p. 809:li.:hp2.Goal::ehp2. Submit the STAF service request(s) specified to run 810when STAFProc shuts down. 811:p.:hp2.Syntax::ehp2. :xph.TRIGGER PHASE Shutdown CONFIRM:exph. 812:p.:hp2.Results::ehp2. If the request is issued from the command line, 813the result, in tabular format, could look like the following: 814:xmp keep=8. 815 ID Machine Service Request RC Result 816 -- ------- ------- ---------------- -- ---------------------------------------- 817 2 local PROCESS START SHELL COMM 0 293 818 AND C:/tests/Tes 819 tTerm.exe 820 6 server1 STAX EXECUTE FILE C:/ 16 STAFConnectionProviderConnect: Timed out 821 stax/jobTerm.xml connecting to endpoint: select() timeou 822 t: 22, Endpoint: tcp://server1 823:exmp. 824:eul. 825.* 826.*--------------------------------------------------------------------- 827.* 828:ih1.service commands 829:ih2.ENABLE 830:i3.LifeCycle service 831:h3.ENABLE 832Allows you to enable a registration for the LifeCycle service. 833This means that the STAF service request for this registration will be 834submitted when STAFProc starts up or shuts down (depending on the phase 835specified for the registration). 836 837:h4.Syntax 838:xmp. 839ENABLE ID <Registration ID> 840:exmp. 841:p.:xph.ID:exph. specifies the registration ID which is to be enabled. 842 843:h4.Security 844:p.&seclvl. 5. 845 846:h4.Return Codes 847:p.All return codes are documented in :hdref refid=retcode.. 848 849:h4.Results 850:p.If successful, the result buffer will be empty. 851Note that an error will not be returned if the registration ID is already 852enabled. 853 854:h4.Examples 855:ul. 856:li.:hp2.Goal::ehp2. Enable registration ID 2. 857:p.:hp2.Syntax::ehp2. 858:p.:xph.ENABLE ID 2:exph. 859:eul. 860.* 861.*--------------------------------------------------------------------- 862.* 863:ih1.service commands 864:ih2.DISABLE 865:i3.LifeCycle service 866:h3.DISABLE 867Allows you to disable a registration for the LifeCycle service. 868This means that the STAF service request for this registration will not be 869submitted when STAFProc starts up or shuts down (depending on the phase 870specified for the registration). 871 872:h4.Syntax 873:xmp. 874DISABLE ID <Registration ID> 875:exmp. 876:p.:xph.ID:exph. specifies the registration ID which is to be disabled. 877 878:h4.Security 879:p.&seclvl. 5. 880 881:h4.Return Codes 882:p.All return codes are documented in :hdref refid=retcode.. 883 884:h4.Results 885:p.If successful, the result buffer will be empty. 886Note that an error will not be returned if the registration ID is already 887disabled. 888 889:h4.Examples 890:ul. 891:li.:hp2.Goal::ehp2. Enable registration ID 2. 892:p.:hp2.Syntax::ehp2. 893:p.:xph.ENABLE ID 2:exph. 894:eul. 895.* 896.*--------------------------------------------------------------------- 897.* 898:ih1.error codes 899:i2.LifeCycle service 900:h3.LifeCycle Error Code Reference 901:p.All return codes from the LifeCycle service are documented in :hdref refid=retcode.. 902.* 903.*--------------------------------------------------------------------- 904.* 905:ih1.service logging 906:i2.LifeCycle service 907:h3 id=lifecycleServiceLog.LifeCycle Service Logging 908:p. 909The STAF LifeCycle service maintains a STAF machine log where it writes 910information about the STAF service requests that have been registered with 911the LifeCycle service and that it has submitted. When debugging a problem 912with a registration for the LifeCycle service, be sure to check the LifeCycle 913service log to determine the results of STAF service requests submitted by 914the LifeCycle service. 915:p. 916The logname for the STAF LifeCycle service is LIFECYCLE. 917Note that tags like :xph.[ID=<id>]:exph. in the log entries can be useful 918when querying the LifeCycle service log by using the :xph.CONTAINS:exph. 919option in the LOG QUERY request. 920:p. 921For example: 922:p. 923:ul. 924:li.To query the entries for registration ID 1 in the LifeCycle service log 925on the local machine, you could specify: 926:p. 927:xmp. 928STAF local LOG QUERY MACHINE {STAF/Config/MachineNickname} LOGNAME LIFECYCLE CONTAINS "[ID=1]" 929Response 930-------- 931Date-Time Level Message 932----------------- ----- ------------------------------------------------------- 93320071127-17:45:19 Info [ID=1] [client10.company.com, STAF/Client, 24] Register 934 request: register phase Startup machine local service 935 PROCESS request &colon.38&colon.START SHELL COMMAND C:/tests/TestA. 936 exe priority 25 description &colon.9&colon.Run TestA 93720071127-18:05:56 Info [ID=1] [client10.company.com, STAF/Client, 48] [TRIGGER 938 Startup] Submitted: STAF local PROCESS START SHELL COM 939 MAND C:/tests/TestA.exe 94020071127-18:05:56 Info [ID=1] [client10.company.com, STAF/Client, 48] [TRIGGER 941 Startup] Completed. RC=0, Result=49 94220071128-11:37:37 Info [ID=1] [client10.company.com, STAF_Process, 1] [TRIGGER 943 Startup] Submitted: STAF local PROCESS START SHELL COM 944 MAND C:/tests/TestA.exe 94520071128-11:37:37 Info [ID=1] [client10.company.com, STAF_Process, 1] [TRIGGER 946 Startup] Completed. RC=0, Result=22 947:exmp. 948:p. 949:li.To query the entries for registration ID 2 in the LifeCycle service log 950on the local machine, you could specify: 951:p. 952:xmp. 953STAF local lOG QUERY MACHINE {STAF/Config/MachineNickname} LOGNAME LIFECYCLE CONTAINS "[ID=2]" 954Response 955-------- 956Date-Time Level Message 957----------------- ----- ------------------------------------------------------- 95820071127-17:46:18 Info [ID=2] [client10.company.com, STAF/Client, 25] Register 959 request: register phase Shutdown machine local service 960 PROCESS request &colon.41&colon.START SHELL COMMAND C:/tests/TestT 961 erm.exe priority 25 96220071127-18:08:54 Info [ID=2] [client10.company.com, STAF/Client, 50] [TRIGGER 963 Shutdown] Submitted: STAF local PROCESS START SHELL CO 964 MMAND C:/tests/TestTerm.exe 96520071127-18:08:54 Info [ID=2] [client10.company.com, STAF/Client, 50] [TRIGGER 966 Shutdown] Completed. RC=0, Result=51 96720071128-11:36:27 Info [ID=2] [client10.company.com, STAF_Process, 1] [TRIGGER 968 Shutdown] Submitted: STAF local PROCESS START SHELL CO 969 MMAND C:/tests/TestTerm.exe 97020071128-11:36:27 Info [ID=2] [client10.company.com, STAF_Process, 1] [TRIGGER 971 Shutdown] Completed. RC=0, Result=78 972:exmp. 973:eul. 974:p. 975The LifeCycle service will log an entry when the following actions occur: 976:ul. 977:li.When a :xph.REGISTER:exph. request is received, a log entry with level 978"Info" is logged with message: 979:p. 980:xph. 981[ID=<id>] [<orgMachine>, <orgHandleName>, <orgHandle#>] Register request: <request> 982:exph. 983:p. 984where: 985:ul compact. 986:li.:xph.<id>:exph. is the registration ID, 987:li.:xph.<orgMachine>:exph. is the machine that originated the request, 988:li.:xph.<orgHandleName>:exph. is the name or the handle that originated the request, 989:li.:xph.<orgHandle#>:exph. is the handle number that originated the request, 990:li.:xph.<request>:exph. is the :xph.REGISTER:exph. request. 991:eul. 992:p. 993:li.When a :xph.UNREGISTER:exph. request is received, a log entry with 994level "Info" is logged with message: 995:p. 996:xph. 997[ID=<id>] [<orgMachine>, <orgHandleName>, <orgHandle#>] Unregistered. 998:exph. 999:p. 1000where: 1001:ul compact. 1002:li.:xph.<id>:exph. is the registration ID, 1003:li.:xph.<orgMachine>:exph. is the machine that originated the request, 1004:li.:xph.<orgHandleName>:exph. is the name or the handle that originated the request, 1005:li.:xph.<orgHandle#>:exph. is the handle number that originated the request, 1006:eul. 1007:p. 1008:li.When STAFProc is started or when a :xph.TRIGGER PHASE Startup:exph. 1009request is submitted, each enabled registration with phase "Startup" 1010will have its STAF service request submitted and a log entry with level 1011"Info" is logged with message: 1012:xph. 1013[ID=<id>] [<orgMachine>, <orgHandleName>, <orgHandle#>] [TRIGGER Startup] 1014Submitted: STAF <machine> <service> <request> 1015:exph. 1016:p. 1017where: 1018:ul compact. 1019:li.:xph.<id>:exph. is the registration ID, 1020:li.:xph.<orgMachine>:exph. is the machine that originated the request, 1021:li.:xph.<orgHandleName>:exph. is the name or the handle that originated the request, 1022:li.:xph.<orgHandle#>:exph. is the handle number that originated the request, 1023:li.:xph.<machine>:exph. is where the STAF service request was submitted, 1024:li.:xph.<service>:exph. is the service to which the STAF service request was submitted, 1025:li.:xph.<request>:exph. is the STAF service request submitted. 1026:eul. 1027:p. 1028:li.When STAFProc is shutdown or when a :xph.TRIGGER PHASE Shutdown:exph. 1029request is submitted, each enabled registration with phase "Shutdown" 1030will have its STAF service request submitted and a log entry with level 1031"Info" is logged with message: 1032:xph. 1033[ID=<id>] [<orgMachine>, <orgHandleName>, <orgHandle#>] [TRIGGER Shutdown] 1034Submitted: STAF <machine> <service> <request> 1035:exph. 1036:p. 1037where: 1038:ul compact. 1039:li.:xph.<id>:exph. is the registration ID, 1040:li.:xph.<orgMachine>:exph. is the machine that originated the request, 1041:li.:xph.<orgHandleName>:exph. is the name or the handle that originated the request, 1042:li.:xph.<orgHandle#>:exph. is the handle number that originated the request, 1043:li.:xph.<machine>:exph. is where the STAF service request was submitted, 1044:li.:xph.<service>:exph. is the service to which the STAF service request was submitted, 1045:li.:xph.<request>:exph. is the STAF service request submitted. 1046:eul. 1047:p. 1048:li.When a :xph.TRIGGER ID:exph. request for a registration (enabled or 1049disabled) is submitted, its STAF service request will be submitted and 1050a log entry with level "Info" is logged with message: 1051:xph. 1052[ID=<id>] [<orgMachine>, <orgHandleName>, <orgHandle#>] [TRIGGER ID] 1053Submitted: STAF <machine> <service> <request> 1054:exph. 1055:p. 1056where: 1057:ul compact. 1058:li.:xph.<id>:exph. is the registration ID, 1059:li.:xph.<orgMachine>:exph. is the machine that originated the request, 1060:li.:xph.<orgHandleName>:exph. is the name or the handle that originated the request, 1061:li.:xph.<orgHandle#>:exph. is the handle number that originated the request, 1062:li.:xph.<machine>:exph. is where the STAF service request was submitted, 1063:li.:xph.<service>:exph. is the service to which the STAF service request was submitted, 1064:li.:xph.<request>:exph. is the STAF service request submitted. 1065:eul. 1066:p. 1067:li.When STAFProc is started or when a :xph.TRIGGER PHASE Startup:exph. 1068request is submitted, for each disabled registration with phase "Startup", 1069a log entry with level "Info" is logged with message: 1070:xph. 1071[ID=<id>] ID is disabled. STAF service request not submitted. 1072:exph. 1073:p. 1074where: 1075:ul compact. 1076:li.:xph.<id>:exph. is the registration ID of the disabled registration. 1077:eul. 1078:p. 1079:li.When STAFProc is shutdown or when a :xph.TRIGGER PHASE Shutdown:exph. 1080request is submitted, for each disabled registration with phase "Shutdown", 1081a log entry with level "Info" is logged with message: 1082:xph. 1083[ID=<id>] ID is disabled. STAF service request not submitted. 1084:exph. 1085:p. 1086where: 1087:ul compact. 1088:li.:xph.<id>:exph. is the registration ID of the disabled registration. 1089:eul. 1090:p. 1091:li.When a submitted STAF service request has completed, a log entry 1092with level "Info" is logged with message: 1093:xph. 1094[ID=<id>] [<orgMachine>, <orgHandleName>, <orgHandle#>] 1095Completed. RC=<rc>, Result=<result> 1096:exph. 1097:p. 1098where: 1099:ul compact. 1100:li.:xph.<id>:exph. is the registration ID, 1101:li.:xph.<orgMachine>:exph. is the machine that originated the request, 1102:li.:xph.<orgHandleName>:exph. is the name or the handle that originated the request, 1103:li.:xph.<orgHandle#>:exph. is the handle number that originated the request, 1104:li.:xph.<rc>:exph. is the return code from the STAF service request that was submitted, 1105:li.:xph.<result>:exph. is the result from the STAF service request that was submitted. 1106:eul. 1107:p. 1108:li.When an :xph.UPDATE:exph. request is received, a log entry with 1109level "Info" is logged with message: 1110:xph. 1111[ID=<id>] [<orgMachine>, <orgHandleName>, <orgHandle#>] 1112Update request: <request> 1113:exph. 1114:p. 1115where: 1116:ul compact. 1117:li.:xph.<id>:exph. is the registration ID, 1118:li.:xph.<orgMachine>:exph. is the machine that originated the request, 1119:li.:xph.<orgHandleName>:exph. is the name or the handle that originated the request, 1120:li.:xph.<orgHandle#>:exph. is the handle number that originated the request, 1121:li.:xph.<request>:exph. is the UPDATE request. 1122:eul. 1123:p. 1124:li.When an :xph.ENABLE:exph. request is received, a log entry with 1125level "Info" is logged with message: 1126:xph. 1127[ID=<id>] [<orgMachine>, <orgHandleName>, <orgHandle#>] Enabled. 1128:exph. 1129:p. 1130where: 1131:ul compact. 1132:li.:xph.<id>:exph. is the registration ID, 1133:li.:xph.<orgMachine>:exph. is the machine that originated the request, 1134:li.:xph.<orgHandleName>:exph. is the name or the handle that originated the request, 1135:li.:xph.<orgHandle#>:exph. is the handle number that originated the request, 1136:eul. 1137:p. 1138:li.When a :xph.DISABLE:exph. request is received, a log entry with 1139level "Info" is logged with message: 1140:xph. 1141[ID=<id>] [<orgMachine>, <orgHandleName>, <orgHandle#>] Disabled. 1142:exph. 1143:p. 1144where: 1145:ul compact. 1146:li.:xph.<id>:exph. is the registration ID, 1147:li.:xph.<orgMachine>:exph. is the machine that originated the request, 1148:li.:xph.<orgHandleName>:exph. is the name or the handle that originated the request, 1149:li.:xph.<orgHandle#>:exph. is the handle number that originated the request, 1150:eul. 1151:eul. 1152