1 /*****************************************************************************/ 2 /* Software Testing Automation Framework (STAF) */ 3 /* (C) Copyright IBM Corp. 2001 */ 4 /* */ 5 /* This software is licensed under the Eclipse Public License (EPL) V1.0. */ 6 /*****************************************************************************/ 7 8 package com.ibm.staf; 9 10 /** 11 * This class is used to return the result from the <code>STAFHandle</code> 12 * class's <code>submit2</code> method. It contains both the STAF return code 13 * as well as the result string. 14 * <p> 15 * In addition, if auto-unmarshalling is enabled for the handle (which it is 16 * by default), it also contains the marshalling context for the result (that 17 * is, the unmarshalled result) and the result object (that is, the root 18 * object of the marshalling context). Otherwise, if auto-unmarshalling is 19 * disabled for the handle that called the <code>submit2</code> method, the 20 * <code>resultContext</code> and <code>resultObj</code> fields will be set to 21 * <code>null</code>. 22 * <p> 23 * It is typically used in places where you wish to avoid catching exceptions 24 * when using STAF or where you want the result to be auto-unmarshalled. 25 * <p> 26 * This class also contains the constant definitions for all the STAF return 27 * codes. These return codes are common to STAFResult and STAFException. 28 */ 29 public class STAFResult 30 { 31 /** 32 * This constructs a STAF result with return code 0 and an empty result 33 * buffer. 34 */ STAFResult()35 public STAFResult() { rc = STAFResult.Ok; result = new String(); } 36 37 /** 38 * This constructs a STAF result with the specified return code and an 39 * empty result buffer. 40 * 41 * @param theRC the return code 42 */ STAFResult(int theRC)43 public STAFResult(int theRC) { rc = theRC; result = new String(); } 44 45 /** 46 * This constructs a STAF result with the specified return code and result 47 * buffer. 48 * 49 * @param theRC the return code 50 * @param theResult the result buffer 51 */ STAFResult(int theRC, String theResult)52 public STAFResult(int theRC, String theResult) 53 { 54 rc = theRC; 55 result = theResult; 56 } 57 58 /** 59 * This constructs a STAF result with the specified return code and result 60 * buffer and allows you to specify a flag indicating whether to unmarshall 61 * the result automatically. 62 * 63 * @param theRC the return code 64 * @param theResult the result buffer 65 * @param doUnmarshallResult a flag indicating whether to unmarshall the 66 * result automatically 67 */ STAFResult(int theRC, String theResult, boolean doUnmarshallResult)68 public STAFResult(int theRC, String theResult, boolean doUnmarshallResult) 69 { 70 rc = theRC; 71 result = theResult; 72 73 if (doUnmarshallResult) 74 { 75 resultContext = STAFMarshallingContext.unmarshall(theResult); 76 resultObj = resultContext.getRootObject(); 77 } 78 } 79 80 /** 81 * The return code 82 */ 83 public int rc; 84 85 /** 86 * The result buffer 87 */ 88 public String result; 89 90 /** 91 * The result object (that is, the root object of the marshalling context). 92 * It is initialized to <code>null</code> and will only be assigned if 93 * auto-unmarshalling is enabled. 94 */ 95 public Object resultObj = null; 96 97 /** 98 * The marshalling context for the result (that is, the unmarshalled result). 99 * It is initialized to <code>null</code> and will only be assigned if 100 * auto-unmarshalling is enabled. 101 */ 102 public STAFMarshallingContext resultContext = null; 103 104 /** 105 * A return code indicating success. 106 */ 107 public static final int Ok = 0; 108 109 /** 110 * A return code indicating that a process has tried to call an invalid 111 * internal STAF API. If this error occurs, report it to the authors. 112 */ 113 public static final int InvalidAPI = 1; 114 115 /** 116 * A return code indicating you have tried to submit a request to a 117 * service that is unknown to STAFProc. Verify that you have correctly 118 * registered the service. 119 */ 120 public static final int UnknownService = 2; 121 122 /** 123 * A return code indicating you are passing an invalid handle to a STAF 124 * API. Ensure that you are using the handle you received when you 125 * registered with STAF. 126 */ 127 public static final int InvalidHandle = 3; 128 129 /** 130 * A return code indicating you are trying to register a process with one 131 * name when that process has already been registered with a different 132 * name. If you register the same process multiple times, ensure that you 133 * use the same name on each registration call. 134 * <p> 135 * Note: If you receive this error code when trying to perform an 136 * operation other than registering a service, report it to the authors. 137 */ 138 public static final int HandleAlreadyExists = 4; 139 140 /** 141 * A return code indicating you are trying to perform an operation on a 142 * handle that does not exist. For example, you may be trying to stop a 143 * process, but you are specifying the wrong handle. 144 */ 145 public static final int HandleDoesNotExist = 5; 146 147 /** 148 * A return code indicating an unknown error has occurred. This error is 149 * usually an indication of an internal STAF error. If this error occurs, 150 * report it the authors. 151 */ 152 public static final int UnknownError = 6; 153 154 /** 155 * A return code indicating you have submitted an improperly formatted 156 * request to a service. See the service's User Guide for for the syntax 157 * of the service's requests, or contact the provider of the service. 158 * <p> 159 * Note: Additional information regarding the exact syntax error may be 160 * provided in the result passed back from the submit call. 161 */ 162 public static final int InvalidRequestString = 7; 163 164 /** 165 * A return code indicating an internal error with the service to which 166 * a request was submitted. If this error occurs, report it to the 167 * authors and the service provider. 168 */ 169 public static final int InvalidServiceResult = 8; 170 171 /** 172 * A return code indicating an internal error in an external Rexx service. 173 * If this error occurs, report it to the authors and the service 174 * provider. 175 * <p> 176 * Note: The actual Rexx error code will be returned in the result passed 177 * back from the submit call. 178 */ 179 public static final int REXXError = 9; 180 181 /** 182 * A return code indicating that a base operating system error was 183 * encountered. 184 * <p> 185 * Note: The actual base operating system error code, and possibly 186 * additional information about the error, will be returned in the result 187 * passed back from the submit call. 188 */ 189 public static final int BaseOSError = 10; 190 191 /** 192 * A return code indicating you are trying to perform an invalid operation 193 * on a process that has already completed. For example, you may be trying 194 * to stop the process or register for a process end notification. 195 */ 196 public static final int ProcessAlreadyComplete = 11; 197 198 /** 199 * A return code indicating you are trying to free process information for 200 * a process that is still executing. 201 */ 202 public static final int ProcessNotComplete = 12; 203 204 /** 205 * A return code indicating you are trying to get, remove, or resolve a 206 * variable that does not exist. Remember that variables are case 207 * sensitive. The name of the variable that does not exist will be in the 208 * result passed back from the submit call. 209 */ 210 public static final int VariableDoesNotExist = 13; 211 212 /** 213 * A return code indicating you have requested to resolve a string that 214 * cannot be resolved. This indicates that you have exceeded the 215 * resolution depth of the VAR service. The most common cause of this is 216 * recursive variables definitions. 217 */ 218 public static final int UnResolvableString = 14; 219 220 /** 221 * A return code indicating the string you requested to be resolved has a 222 * non-matching left or right curly brace. Ensure that all variable 223 * references have both left and right curly braces. 224 */ 225 public static final int InvalidResolveString = 15; 226 227 /** 228 * A return code indicating that STAFProc was not able to submit the 229 * request to the requested endpoint (i.e. target machine). This error 230 * usually indicates one or more of the following: 231 * <ul> 232 * <li>STAFProc is not running on the target machine. 233 * <li>The requested endpoint is not valid. 234 * <li>The network interface or port for the requested endpoint is not 235 * supported. 236 * <li>A firewall is blocking communication via the port for the requested 237 * endpoint. 238 * <li>A secure network interface is being used to communicate to a 239 * machine that doesn't have a secure network interface configured with 240 * the same certificate. 241 * </ul> 242 * <p> 243 * Alternatively, you may need to increase your CONNECTTIMEOUT value for 244 * the network interface and/or increase your CONNECTATTEMPTS value in 245 * your STAF.cfg file. 246 */ 247 public static final int NoPathToMachine = 16; 248 249 /** 250 * A return code indicating that there was an error opening the requested 251 * file. Some possible explanations are that the file/path does not exist, 252 * contains invalid characters, or is locked. 253 * <p> 254 * Note: Additional information regarding which file could not be opened 255 * may be provided in the result passed back from the submit call. 256 */ 257 public static final int FileOpenError = 17; 258 259 /** 260 * A return code indicating that there was an error while trying to read 261 * data from a file. 262 * <p> 263 * Note: Additional information regarding which file could not be read 264 * from may be provided in the result passed back from the submit call. 265 */ 266 public static final int FileReadError = 18; 267 268 /** 269 * A return code indicating that there was an error while trying to write 270 * data to a file. 271 * <p> 272 * Note: Additional information regarding which file could not be written 273 * to may be provided in the result passed back from the submit call. 274 */ 275 public static final int FileWriteError = 19; 276 277 /** 278 * A return code indicating that there was an error while trying to delete 279 * a file or directory. 280 * <p> 281 * Note: Additional information regarding which file or directory could not 282 * be deleted may be provided in the result passed back from the submit 283 * call. 284 */ 285 public static final int FileDeleteError = 20; 286 287 /** 288 * A return code indicating that STAFProc is not running on the local 289 * machine with the same STAF_INSTANCE_NAME (and/or the same STAF_TEMP_DIR 290 * if on a Unix machine). 291 * <p> 292 * Notes: 293 * <ul> 294 * <li>If the STAF_INSTANCE_NAME environment variable is not set, it 295 * defaults to "STAF". 296 * <li>On Unix, if the STAF_TEMP_DIR environment variable is not set, it 297 * defaults to "/tmp". This environment variable is not used on Windows. 298 * <li>This error can also occur when submitting a request using the local 299 * IPC interface on a Unix machine if the socket file that the local 300 * interface uses has been inadvertently deleted. 301 * <li>On Windows, with User Account Controls (UAC) enabled, if STAFProc.exe 302 * is being run as an Administrator, this error will occur if a STAF service 303 * request is not also run as an Administrator (e.g. from an "Administrator: 304 * Command Prompt") or if programs that submit STAF service requests using 305 * STAF APIs for Java, C/C++, Perl, Python, or Tcl are not run an an 306 * Administrator. See section "5.1.2 Running STAFProc on Windows with User 307 * Account Controls (UAC) Enabled" in the STAF User's Guide for more 308 * information. 309 * <li>More information on this error may be displayed if you set special 310 * environment variable STAF_DEBUG_21=1 and resubmit your STAF service 311 * request. 312 * </ul> 313 */ 314 public static final int STAFNotRunning = 21; 315 316 /** 317 * A return code indicating an error transmitting data across the network, 318 * or to the local STAF process. For example, you would receive this error 319 * if STAFProc.exe was terminated in the middle of a service request, or 320 * if a bridge went down in the middle of a remote service request. This 321 * can also indicate that the requested endpoint is not valid (e.g. it has 322 * an invalid network interface and port combination such as a non-secure 323 * tcp interface with the port for a secure ssl interface). 324 */ 325 public static final int CommunicationError = 22; 326 327 /** 328 * A return code indicating you have requested to delete a trustee, and the 329 * trustee does not exist. Verify that you have specified the correct 330 * trustee. 331 */ 332 public static final int TrusteeDoesNotExist = 23; 333 334 /** 335 * A return code indicating You have attempted to set a machine or default 336 * trust level to an invalid level. The valid trust levels are from zero 337 * to five. 338 */ 339 public static final int InvalidTrustLevel = 24; 340 341 /** 342 * A return code indicating you have submitted a request for which you do 343 * not have the required trust level to perform the request. 344 * <p> 345 * Note: Additional information regarding the required trust level may be 346 * provided in the result passed back from the submit call. 347 */ 348 public static final int AccessDenied = 25; 349 350 /** 351 * A return code indicating that an external service encountered a problem 352 * when trying to register with STAF. Ensure that STAF has been properly 353 * installed and configured. 354 */ 355 public static final int STAFRegistrationError = 26; 356 357 /** 358 * A return code indicating an error with the configuration of an external 359 * service. One possible explanation is that the LIBRARY you specified 360 * when configuring the service does not exist. Or, if you specified the 361 * EXECUTE option, verify that the executable exists and has the execute 362 * permission. Or, if you specified the PARMS option, verify that all of 363 * the service configuration are valid. Consult the appropriate 364 * documentation for the service to verify whether you have configured the 365 * service properly, or contact the service provider. 366 * <p> 367 * Note: Additional information regarding why the service configuration 368 * failed may be provided in the result passed back from the submit call. 369 */ 370 public static final int ServiceConfigurationError = 27; 371 372 /** 373 * A return code indicating that you are trying to queue a message to a 374 * handle's queue, but the queue is full. The maximum queue size can be 375 * increased by using the MAXQUEUESIZE statement in the STAF Configuration 376 * File. 377 */ 378 public static final int QueueFull = 28; 379 380 /** 381 * A return code indicating that you tried to GET or PEEK a particular 382 * element in a queue, but no such element exists, or the queue is empty. 383 */ 384 public static final int NoQueueElement = 29; 385 386 /** 387 * A return code indicating that you are trying to remove a message 388 * notification for a machine/process/priority combination which does not 389 * exist in the notification list. 390 */ 391 public static final int NotifieeDoesNotExist = 30; 392 393 /** 394 * A return code indicating that a process has tried to call an invalid 395 * level of an internal STAF API. If this error occurs, report it to the 396 * authors. 397 */ 398 public static final int InvalidAPILevel = 31; 399 400 /** 401 * A return code indicating that you are trying to unregister a service 402 * that is not unregisterable. Note that internal services are not 403 * unregisterable. 404 */ 405 public static final int ServiceNotUnregisterable = 32; 406 407 /** 408 * A return code indicating that the service you requested is not 409 * currently able to accept requests. The service may be in the process of 410 * initializing or terminating. 411 */ 412 public static final int ServiceNotAvailable = 33; 413 414 /** 415 * A return code indicating that you are trying to release, query, or 416 * delete a semaphore that does not exist. 417 */ 418 public static final int SemaphoreDoesNotExist = 34; 419 420 /** 421 * A return code indicating that you are trying to release a semaphore for 422 * which your process is not the current owner. 423 */ 424 public static final int NotSemaphoreOwner = 35; 425 426 /** 427 * A return code indicating that you are trying to delete either a mutex 428 * semaphore that is currently owned or an event semaphore that has 429 * waiting processes. 430 */ 431 public static final int SemaphoreHasPendingRequests = 36; 432 433 /** 434 * A return code indicating that you submitted a request with a timeout 435 * value and the request did not complete within the requested time. 436 */ 437 public static final int Timeout = 37; 438 439 /** 440 * A return code indicating an error performing a Java native method call. 441 * A description of the error will be returned in the result passed back 442 * from the submit call. 443 */ 444 public static final int JavaError = 38; 445 446 /** 447 * A return code indicating an error performing a codepage conversion. 448 * The most likely cause of this error is that STAF was not properly 449 * installed. However, it is possible that you are currently using a 450 * codepage that was not present or specified during STAF installation. 451 */ 452 public static final int ConverterError = 39; 453 454 /** 455 * A return code indicating that there was an error while trying to move a 456 * file or directory. 457 * <p> 458 * Note: Additional information regarding the error may be provided in the 459 * result passed back from the submit call. 460 */ 461 public static final int MoveError = 40; 462 463 /** 464 * A return code indicating that an invalid object was specified to a STAF 465 * API. If you receive this return code via a standard STAFSubmit call, 466 * report it to the authors and the service provider. 467 */ 468 public static final int InvalidObject = 41; 469 470 /** 471 * A return code indicating that an invalid parameter was specified to a 472 * STAF API. If you receive this return code via a standard STAFSubmit 473 * call, report it to the authors and the service provider. 474 */ 475 public static final int InvalidParm = 42; 476 477 /** 478 * A return code indicating that the specified Request Number was not 479 * found. The specified Request Number may be invalid, or the request's 480 * information may no longer be available from the Service Service (for 481 * example, if the SERVICE FREE command had previously been issued for 482 * the request number). 483 */ 484 public static final int RequestNumberNotFound = 43; 485 486 /** 487 * A return code indicating that an invalid Asynchronous submit option was 488 * specified. 489 */ 490 public static final int InvalidAsynchOption = 44; 491 492 /** 493 * A return code indicating that the specified request is not complete. 494 * This error code would be returned, for example, if you requested the 495 * result of a request which has not yet completed. 496 */ 497 public static final int RequestNotComplete = 45; 498 499 /** 500 * A return code indicating that the userid/password you specified could 501 * not be authenticated. The userid/password may not be valid or 502 * authentication may be disabled. 503 */ 504 public static final int ProcessAuthenticationDenied = 46; 505 506 /** 507 * A return code indicating that an invalid value was specified. This is 508 * closely related to the Invalid Request String return code, but 509 * indicates that a specific value in the request is invalid. For example, 510 * you may not have specified a number where a number was expected. 511 * <p> 512 * Note: Additional information regarding which value is invalid may be 513 * provided in the result passed back from the submit call. 514 */ 515 public static final int InvalidValue = 47; 516 517 /** 518 * A return code indicating that the item you specified does not exist. 519 * <p> 520 * Note: Additional information regarding which item could not be found 521 * may be provided in the result passed back from the submit call. 522 */ 523 public static final int DoesNotExist = 48; 524 525 /** 526 * A return code indicating that the item you specified already exists. 527 * <p> 528 * Note: Additional information regarding which item already exists may 529 * be provided in the result passed back from the submit call. 530 */ 531 public static final int AlreadyExists = 49; 532 533 /** 534 * A return code indicating that you have tried to delete a directory, but 535 * that directory is not empty. 536 * <p> 537 * Note: Additional information specifying the directory which could not 538 * be deleted may be provided in the result passed back from the submit 539 * call. 540 */ 541 public static final int DirectoryNotEmpty = 50; 542 543 /** 544 * A return code indicating that you have tried to copy a directory, but 545 * errors occurred during the copy. 546 * <p> 547 * Note: Additional information specifying the entries which could not be 548 * copied may be provided in the result passed back from the submit call. 549 */ 550 public static final int DirectoryCopyError = 51; 551 552 /** 553 * A return code indicating that you tried to record diagnostics data, but 554 * diagnostics have not been enabled. You must enable diagnostics before 555 * you can record diagnostics data. 556 */ 557 public static final int DiagnosticsNotEnabled = 52; 558 559 /** 560 * A return code indicating that the user, credentials, and/or 561 * authenticator you specified could not be authenticated. The 562 * user/credentials may not be valid or the authenticator may not be 563 * registered. 564 * <p> 565 * Note: Additional information specifying why authentication was denied 566 * may be provided in the result passed back from the submit call. 567 */ 568 public static final int HandleAuthenticationDenied = 53; 569 570 /** 571 * A return code indicating that the handle is already authenticated. The 572 * handle must be unauthenticated in order to be authenticated. 573 */ 574 public static final int HandleAlreadyAuthenticated = 54; 575 576 /** 577 * A return code indicating that the version of STAF (or the version of 578 * a STAF service) is lower than the minimum required version. 579 */ 580 public static final int InvalidSTAFVersion = 55; 581 582 /** 583 * A return code indicating that the request has been cancelled. 584 * <p> 585 * Note: Additional information specifying why the request was cancelled 586 * may be provided in the result passed back from the submit call. 587 */ 588 public static final int RequestCancelled = 56; 589 590 /** 591 * A return code indicating that a problem occurred creating a new thread. 592 * One possible explanation is that there's not enough memory available to 593 * create a new thread. 594 * <p> 595 * Note: Additional information specifying why creating a new thread failed 596 * may be provided in the result passed back from the submit call. 597 */ 598 public static final int CreateThreadError = 57; 599 600 /** 601 * A return code indicating that the size of a file exceeded the maximum 602 * size allowed (e.g. per the MAXRETURNFILESIZE operational parameter or 603 * per the MAXRETURNFILESIZE setting for the STAX service). A maximum file 604 * size is usually set to prevent the creation of result strings that 605 * require more memory than is available which can cause errors or crashes. 606 * <p> 607 * Note: Additional information specifying why this error occurred may be 608 * provided in the result passed back from the submit call. 609 */ 610 public static final int MaximumSizeExceeded = 58; 611 612 /** 613 * A return code indicating that a new handle could not be created or 614 * registered because the maximum number of active handles allowed by 615 * STAF has been exceeded. You need to delete one or more handles that 616 * are no longer being used. The Handle service's LIST HANDLES SUMMARY 617 * request provides information on the maximum number of active STAF 618 * handles and this may be helpful in better understanding why this error 619 * occurred. 620 */ 621 public static final int MaximumHandlesExceeded = 59; 622 623 /** 624 * A return code indicating that you cannot cancel a pending request your 625 * handle did not submit unless you specify the FORCE option. 626 */ 627 public static final int NotRequester = 60; 628 629 /** 630 * Error codes of 4000 and beyond are service specific error codes. Either 631 * see the appropriate section in this document for the syntax of the 632 * service's requests, or contact the provider of the service. 633 */ 634 public static final int UserDefined = 4000; 635 } 636