API Return Codes
Note: In some shell environments, return codes above 255 may be returned modulo256. This can, in particular, cause service return codes (which range from4000 upward) to be mistaken for (possibly) non-existent common STAF returncodes. For
example, if a service returned the return code 4010, this mightappear to be the return code 170 (4010 modulo 256) in a shellenvironment.
Table 1. STAF API Return Codes
| Error Code | Meaning | Comment |
|---|---|---|
| 0 | No error | |
| 1 | Invalid API | This indicates that a process has tried to call an invalid internal STAF API.If this error occurs, report it to the authors. |
| 2 | Unknown Service | You have tried to submit a request to a service that is unknown to STAFProc.Verify that you have correctly registered the service. |
| 3 | Invalid Handle | You are passing an invalid handle to a STAF API. Ensure that you are usingthe handle you received when you registered with STAF. |
| 4 | Handle already exists | This indicates that you are trying to register a process with one name whenthat process has already been registered with a different name. If youregister the same process multiple times, ensure that you use the same nameon each registration call. Note: If you receive this error code when trying to perform an operationother than registering a service, report it to the authors. |
| 5 | Handle does not exist | You are trying to perform an operation on a handle that does not exist.For example, you may be trying to stop a process, but you are specifying thewrong handle. |
| 6 | Unknown Error | An unknown error has occurred. This error is usually an indication of aninternal STAF error. If this error occurs, report it the authors. |
| 7 | Invalid Request String | You have submitted an improperly formatted request to a service. See theappropriate section in this document for the syntax of the service's requests,or contact the provider of the service.
Note: Additional information regarding the exact syntax error may be providedin the result passed back from the submit call. |
| 8 | Invalid Service Result | This indicates an internal error with the service to which a request wassubmitted. If this error occurs, report it to the authors and the serviceprovider. |
| 9 | Rexx Error | This indicates an internal error in an external Rexx service. If this erroroccurs, report it to the authors and the service provider.
Note: The actual Rexx error code will be returned in the result passed backfrom the submit call. |
| 10 | Base OS Error | This indicates that a base operating system error was encountered.
Note: The actual base operating system error code, and possibly additionalinformation about the error, will be returned in the result passed backfrom the submit call. |
| 11 | Process Already Complete | You are trying to perform an invalid operation on a process that hasalready completed. For example, you may be trying to stop the process orregister for a process end notification. |
| 12 | Process Not Complete | You are trying to free process information for a process that is stillexecuting. |
| 13 | Variable Does Not Exist | You are trying to get, remove, or resolve a variable that does not exist.Remember that variables are case sensitive. The name of the variable thatdoes not exist will be in the result passed back from the submit call. |
| 14 | UnResolvable String | You have requested to resolve a string that cannot be resolved. Thisindicates that you have exceeded the resolution depth of the VAR service. Themost common cause of this is recursive variables definitions. |
| 15 | Invalid Resolve String | The string you requested to be resolved has a non-matching left or rightcurly brace. Ensure that all variable references have both left and rightcurly braces. |
| 16 | No Path To Endpoint | This indicates that STAFProc was not able to submit the request tothe requested endpoint (i.e. target machine). This error usually indicatesone or more of the following:
Alternatively, you may need to increase your CONNECTTIMEOUT value for thenetwork interface and/or increase your CONNECTATTEMPTS value in your STAF.cfgfile. |
| 17 | File Open Error | This indicates that there was an error opening the requested file.Some possible explanations are that the file/path does not exist, containsinvalid characters, or is locked.
Note: Additional information regarding which file could not be opened may beprovided in the result passed back from the submit call. |
| 18 | File Read Error | This indicates that there was an error while trying to read data from a file.
Note: Additional information regarding which file could not be read from may beprovided in the result passed back from the submit call. |
| 19 | File Write Error | This indicates that there was an error while trying to write data to a file.
Note: Additional information regarding which file could not be written to maybe provided in the result passed back from the submit call. |
| 20 | File Delete Error | This indicates that there was an error while trying to delete a file ordirectory.
Note: Additional information regarding which file or directory could not bedeleted may be provided in the result passed back from the submit call. |
| 21 | STAF Not Running | This indicates that STAFProc is not running on the local machine with thesame STAF_INSTANCE_NAME (and/or the same STAF_TEMP_DIR if on a Unix machine).
Notes:
|
| 22 | Communication Error | This indicates an error transmitting data across the network, or to thelocal STAF process. For example, you would receive this error if STAFProc.exewas terminated in the middle of a service request, or if a bridge went downin the middle of a remote service request. This can also indicate that therequested endpoint is not valid (e.g. it has an invalid network interface andport combination such as a non-secure tcp interface with the port for a securessl interface). |
| 23 | Trustee Does Not Exist | You have requested to delete a trustee, and the trustee does not exist.Verify that you have specified the correct trustee. |
| 24 | Invalid Trust Level | You have attempted to set a machine or default trust level to an invalidlevel. The valid trust levels are from zero to five. |
| 25 | Insufficient Trust Level | You have submitted a request for which you do not have the requiredtrust level to perform the request.
Note: Additional information regarding the required trust level may beprovided in the result passed back from the submit call. |
| 26 | STAF Registration Error | This indicates that an external service encountered a problem when tryingto register with STAF. Ensure that STAF has been properly installed andconfigured. |
| 27 | Service Configuration Error | This indicates an error with the configuration of an external service. One possible explanation is that the LIBRARY you specified when configuring theservice does not exist. Or, if you specified the EXECUTE option, verify thatthe executable exists and has the execute permission. Or, if you specified thePARMS option, verify that all of the service configuration are valid. Consultthe appropriate documentation for the service to verify whether you haveconfigured the service properly, or contact the service provider. Note: Additional information regarding why the service configuration failedmay be provided in the result passed back from the submit call. |
| 28 | Queue Full | This indicates that you are trying to queue a message to a handle's queue,but the queue is full. The maximum queue size can be increased by usingthe MAXQUEUESIZE statement in the STAF Configuration File. |
| 29 | No Queue Element | This indicates that you tried to GET or PEEK a particular element in aqueue, but no such element exists, or the queue is empty. |
| 30 | Notifiee Does Not Exist | This indicates that you are trying to remove a message notification fora machine/process/priority combination which does not exist in thenotification list. |
| 31 | Invalid API Level | This indicates that a process has tried to call an invalid level of aninternal STAF API. If this error occurs, report it to the authors. |
| 32 | Service Not Unregisterable | This indicates that you are trying to unregister a service that is notunregisterable. Note that internal services are not unregisterable. |
| 33 | Service Not Available | This indicates that the service you requested is not currently able toaccept requests. The service may be in the process of initializing orterminating. |
| 34 | Semaphore Does Not Exist | This indicates that you are trying to release, query, or delete a semaphorethat does not exist. |
| 35 | Not Semaphore Owner | This indicates that you are trying to release a semaphore for which yourprocess is not the current owner. |
| 36 | Semaphore Has Pending Requests | This indicates that you are trying to delete either a mutex semaphore thatis currently owned or an event semaphore that has waiting processes. |
| 37 | Timeout | This indicates that you submitted a request with a timeout value and therequest did not complete within the requested time. |
| 38 | Java Error | This indicates an error performing a Java native method call. A descriptionof the error will be returned in the result passed back from the submit call. |
| 39 | Converter Error | This indicates an error performing a codepage conversion. The most likelycause of this error is that STAF was not properly installed. However, it ispossible that you are currently using a codepage that was not present orspecified during STAF installation. |
| 40 | Move Error | This indicates that there was an error while trying to move a file ordirectory.
Note: Additional information regarding the error may be provided in theresult passed back from the submit call. |
| 41 | Invalid Object | This indicates that an invalid object was specified to a STAF API.If you receive this return code via a standard STAFSubmit call, report it tothe authors and the service provider. |
| 42 | Invalid Parm | This indicates that an invalid parameter was specified to a STAF API.If you receive this return code via a standard STAFSubmit call, report it to the authors and the service provider. |
| 43 | Request Number Not Found | This indicates that the specified Request Number was not found. The specified Request Number may be invalid, or the request's information may no longer be available from the Service Service (for example, if the SERVICE FREEcommand had previously been issued for the request number). |
| 44 | Invalid Asynch Option | This indicates that an invalid Asynchronous submit option was specified. |
| 45 | Request Not Complete | This indicates that the specified request is not complete. This error code would be returned, for example, if you requested the result of a request which has not yet completed. |
| 46 | Process Authentication Denied | This indicates that the userid/password you specified could not be authenticated. The userid/password may not be valid or authentication may be disabled. |
| 47 | Invalid Value | This indicates that an invalid value was specified. This is closely relatedto the Invalid Request String return code, but indicates that a specific value in the request is invalid. For example, you may not have specified a number where a number was expected. Note: Additional information regarding which value is invalid may be providedin the result passed back from the submit call. |
| 48 | Does Not Exist | This indicates that the item you specified does not exist.
Note: Additional information regarding which item could not be found may beprovided in the result passed back from the submit call. |
| 49 | Already Exists | This indicates that the item you specified already exists.
Note: Additional information regarding which item already exists may beprovided in the result passed back from the submit call. |
| 50 | Directory Not Empty | This indicates that you have tried to delete a directory, but that directoryis not empty.
Note: Additional information specifying the directory which could not be deletedmay be provided in the result passed back from the submit call. |
| 51 | Directory Copy Error | This indicates that you have tried to copy a directory, but errors occurredduring the copy.
Note: Additional information specifying the entries which could not be copiedmay be provided in the result passed back from the submit call. |
| 52 | Diagnostics Not Enabled | This indicates that you tried to record diagnostics data, but diagnosticshave not been enabled. You must enable diagnostics before you can recorddiagnostics data. |
| 53 | Handle Authentication Failed | This indicates that the user, credentials, and/or authenticator you specifiedcould not be authenticated. The user/credentials may not be valid or theauthenticator may not be registered.
Note: Additional information specifying why authentication was denied may beprovided in the result passed back from the submit call. |
| 54 | Handle Already Authenticated | This indicates that the handle is already authenticated. The handle must beunauthenticated in order to be authenticated. |
| 55 | Invalid STAF Version | This indicates that the version of STAF (or the version of a STAF service)is lower than the minimum required version. |
| 56 | Request cancelled | This indicates that the request has been cancelled.
Note: Additional information specifying why the request was cancelled may beprovided in the result passed back from the submit call. |
| 57 | Create Thread Error | This indicates that a problem occurred creating a new thread. One possibleexplanation is that there's not enough memory available to create a newthread.
Note: Additional information specifying why creating a new thread failed may beprovided in the result passed back from the submit call. |
| 58 | Maximum Size Exceeded | This indicates that the size of a file exceeded the maximum size allowed(e.g. per the MAXRETURNFILESIZE operational parameter or per theMAXRETURNFILESIZE setting for the STAX service).A maximum file size is usually set to prevent the creation of result stringsthat require more memory than is available which can cause errors or crashes. Note: Additional information specifying why this error occurred may beprovided in the result passed back from the submit call. |
| 59 | Maximum Handles Exceeded | This indicates that a new handle could not be created/registeredbecause the maximum number of active handles allowed by STAF has beenexceeded. You need to delete one or more handles that are no longerbeing used. The Handle service's LIST HANDLES SUMMARY request providesinformation on the maximum number of active STAF handles and this may behelpful in better understanding why this error occurred. |
| 60 | Not Pending Requester | You cannot cancel a pending request your handle did not submit unlessyou specify the FORCE option. |
| 4000+ | Service Defined | Error codes of 4000 and beyond are service specific error codes. Eithersee the appropriate section in this document for the syntax of the service'srequests, or contact the provider of the service. |