Message Class 0020 - EntireX ACI - User Error in the API

The user has tried to access a conversation after finishing it with a previous EOC call.

This is a user error. Perhaps an invalid conversation ID was specified. Check the program and correct the error.

This response is given to a RECEIVE call with OPTION=LAST when no data/messages have yet been received. It is not possible to look at the last message if you have not read the first one.

This is a user error. Check the program and correct the error.

This response is given when invalid values for the WAIT or UWTIME or UWSTATP-ADDER fields of the API are specified (for example, non-digits are given or the last character is not one of the valid time units S,M,H).

This is a user error. Check the value for the field in the API of your program.

The user has set the errtext_length in the Broker control block but has not provided an error buffer.

This is a user error. The user should either provide an error buffer or set the errtext_length to 0.

Because a service registered with the option ATTACH does not run normal conversations, the DEREGISTER cannot wait for them to finish. In fact, the attachable service is no longer attachable after the DEREGISTER

Do not use the DEREGISTER option QUIESCE for services that are registered as attach manager (option ATTACH)

An application can register a service either with the option ATTACH or as a normal server (without option ATTACH). The error occurs when an application attempts to do both.

Do not try to register a single server as an attach manager and as a normal server simultaneously

An application can register a service either with the option ATTACH, or as a normal server (without option ATTACH). The error occurs when an application attempts to do both.

Do not try to register a single server as a normal service and as an attach manager simultaneously.

The data/message retrieved is larger than the supplied receive buffer. The data/message has been truncated to the actual length given in RECEIVE-LENGTH field of the API if API version 2 or above is used.

See Error Cases under Using Send and Receive Buffers for information on how to respond to this error code.

The performed function is not valid if only a LOGON call has been performed. This applies to a RECEIVE, DEREGISTER or EOC function. They are not allowed right after a LOGON call.

Do not perform the listed function right after a LOGON. Perform a REGISTER before running the DEREGISTER, perform a SEND or a RECEIVE before running an EOC and accept or establish a conversation before running a RECEIVE.

If AUTOLOGON=NO is defined in the attribute file, all participant applications must perform a LOGON call as the very first Broker call and a LOGOFF call when they have finished communicating with the Broker. If the user is using UOW, clients and servers must do a LOGON. If AUTOLOGON=YES and a LOGON is not done, this error will occur when a SEND with OPTION=SYNC is done. See AUTOLOGON under Broker Attributes.

Make LOGON the very first call and LOGOFF the last call. If necessary, define the attribute AUTOLOGON=YES in order to support automatic LOGON. However, the recommended definition is to force an explicit LOGON call.

The broker stub was unable to initialize the environment.

• Under z/OS, the EXX load library was not concatenated to the STEPLIB chain.

• Under BS2000/OSD, the EXX load library was not assigned to LINK-NAME ETBLIB.

Depends on the operating system:

• z/OS: Make sure the EXX load library is concatenated to the STEPLIB chain. See Step 4: Authorize the Broker STEPLIB Data Sets.

• BS2000/OSD: Make sure the EXX load library is assigned to LINK-NAME ETBLIB. See Linking the Stubs.

USER-ID and TOKEN should be provided for durable subscription.

Supply USER-ID and TOKEN in the Broker control block.

The OPTION / PUBLID combination in the API is invalid. For example, a CONTROL_PUBLICATION was issued with OPTION=SETUSTATUS, and no specific publication ID was given.

This is a user error. Check the program and correct the error.

A request was issued and no topic name was specified.

Specify a topic name.

The value for the USER-ID field of the API is missing. The USER-ID is a mandatory parameter.

This is a user error. Check the value for the USER-ID field in the API of your program.

The value for the FUNCTION field of the API is invalid.

This is a user error. Check the value for the FUNCTION field in the API of your program.

The service is missing or invalid in a Broker call that requires a service, that is, a REGISTER/DEREGISTER or a SEND/RECEIVE/EOC call with no CONV-ID specified.

This is a user error. Make sure that at least one of the following fields has been provided: SERVER-CLASS, SERVER-NAME or SERVICE. Together, these fields define the service.

The value for the SEND-LENGTH field of the API is missing.

This is a user error. A SEND call always requires a send-length. Check the program and correct the error.

The value for the CONV-ID field of the API is invalid, missing, or invalid in combination with the desired function.

This is a user error. A SEND/RECEIVE/EOC/UNDO call requires a valid value for the CONV-ID (CID) field. Check the program and correct the error.

The character fields within the EntireX Broker ACI must not contain the metacharacter '.' or ','. These characters are used as special characters in the communication protocol between the Broker stub and the Broker.

Correct the wrong character in the EntireX Broker ACI.

The FUNCTION / OPTION combination is invalid.

This is a user error. Check the value for the OPTION field in conjunction with the FUNCTION field in the API of your program and correct the error.

The OPTION field of the API contains an unknown value.

This is a user error. Check the value for the OPTION field in the API of your program and correct the error.

The value for the RECEIVE-LENGTH field of the API is missing. RECEIVE calls and blocked SEND calls always require a valid RECEIVE-LENGTH.

This is a user error. Check the program and correct the error.

The EntireX Broker kernel does not recognize the Command and Information Services API version requested.

This is a user error. Please check the following:

• If you are using ETBINFO, ETBCMD or any other Software AG-provided Command and Information Services application: Check that the version of ETBINFO or ETBCMD is the same or earlier than the version of the Broker kernel.

• If you are using your own Command and Information Services application: verify that the Command and Information Services API version will work with the version of EntireX. The following table shows the maximum CIS API version for the respective version of EntireX:

  Broker/EntireX Version	Max. CIS API Version
  ETB 1 or ETB 2	1
  EXX 3,4,5,6	2
  EXX 7.1	3
  EXX 7.2	4
  EXX 7.3	5
  EXX 8.0 or 8.1	6
  EXX 8.2	7
  EXX 9.0	8

• A possible cause for this error is a SEND-LENGTH that is too short. Increase this value if necessary.

The OPTION / CONV-ID combination in the API is invalid. For example, a SEND was issued with OPTION=EOC and CONV-ID=NONE or a RECEIVE with OPTION=LAST and no specific conversation ID (CONV-ID) was given.

This is a user error. Check the program and correct the error.

More than four pointers have been supplied in the parameter list used to call the Broker stub.

Correct the program. A maximum of four pointers can be supplied.

The FUNCTION / WAIT combination in the API is invalid. A WAIT value in the API can be specified for the SEND, RECEIVE and RECEIVE_PUBLICATION functions only.

This is a user error. Check the program and correct the error.

The OPTION / WAIT combination in the API is invalid, that is, a SEND with OPTION=EOC, HOLD or SYNC, or a RECEIVE with OPTION=LAST was issued.

This is a user error. Check the program and correct the error.

This response is given when a client tries to issue a deregister call to EntireX Broker.

Do not issue a DEREGISTER call for clients. Check the program and correct the error.

A client issued a RECEIVE call for new conversations.

This is a user error. Clients cannot issue a RECEIVE with CONV-ID=ANY because a RECEIVE with CONV-ID=ANY must be preceded by a REGISTER call. Check the program and correct the error.

A client has issued a RECEIVE call for new conversations.

This is a user error. Clients cannot issue a RECEIVE with CONV-ID=NEW because a RECEIVE with CONV-ID=NEW must be preceded by a REGISTER call. Check the program and correct the error.

The address of the receive buffer is missing for the Broker call. That is, a RECEIVE or a blocked SEND was issued without the receive buffer address.

This is a user error. Check the program and correct the error.

One of the following errors occurred: Invalid API-TYPE or API-VERSION supplied by user when calling Broker stub. Invalid version supplied by user in internal control blocks when calling Broker stub. Broker detected an invalid or unsupported prefix version specified by stub. Broker does not support the API-VERSION supplied by user.

This is a user error. Check version of Broker stubs and Broker kernel. Determine the stub version by using function FCT_VERSION. Determine the kernel version by using function FCT_KERNELVERS. Correct API-TYPE or API-VERSION in the Broker control block.

A SEND was issued without the send buffer address. Therefore, no address is given to the Broker stub as the second parameter.

This is a user error. Check the program and correct the error.

The ACI control block is missing for the call. No address is given to the Broker stub as the first parameter.

This is a user error. Check the program and correct the error.

The FUNCTION / SERVICE combination provided by the SERVER-CLASS, SERVER-NAME, and SERVICE fields of the API is invalid. That is, a SEND function is used with an asterisk (*) in any of the SERVICE fields.

This is a user error. Check the program and correct the error.

The BROKER-ID field in the API does not contain a valid numeric node ID.

The BROKER-ID in the API should be the same as the BROKER-ID in the Broker attribute file.

The maximum length possible for the send buffer/receive buffer depends on the Broker API version and the transport method (TCP/IP or Entire Net-Work) used, and on the configuration of the EntireX Broker.

Check the API version and the transport method (TCP/IP or Entire Net-Work) used, and the possible maximum length of send buffer/receive buffer for the transport method. See the field SEND-LENGTH of the Broker ACI control block. See SEND-LENGTH under Broker ACI Fields.

Check the Broker attribute MAX-MESSAGE-LENGTH. See MAX-MESSAGE-LENGTH under Broker Attributes.

A shortage of the attached buffers or the intermediate user buffers may also lead to this error, especially when attribute EXTENDED-ACB-SUPPORT is set to "YES" to allow buffers greater than 32 KB to be transmitted using transport method NET. Check the Broker attributes NABS and IUBL under Adabas SVC/Entire Net-Work-specific Attributes under Broker Attributes.

The Broker has returned an invalid status.

Contact Software AG support.

The Broker has returned an invalid conversation status.

Contact Software AG support.

There are two possible error sources:

1. The application has supplied an invalid value for STORE in the Broker ACI control block. See STORE under Broker ACI Fields.

2. The Broker has returned an invalid value for STORE from the kernel.

In situation 1, ensure that the application assigns only a valid value to the field.

In situation 2, contact Software AG support.

A SUBSCRIBE request can be made with option DURABLE. If the user is already subscribed to the topic, the same durability scope must be specified as option. A durable subscriber resubscribes with option DURABLE; a non-durable subscriber resubscribes without option DURABLE. A change of the durability scope requires an UNSUBSCRIBE request.

Apply the correct option.

No publication ID was specified for this CONTROL_PUBLICATION request.

Specify the publication ID.

The application tried to start a conversation when issuing an EntireX Broker command operation. The internal service should be used in non-conversational mode only (CID=NONE).

Change your code.

An INFO service request has been started with CID not equal NEW. Because INFO services are conversational, a new conversation must be started with every initial SEND command. The returning information can be spread across several messages which must be received separately.

Always send INFO requests with CID=NEW.

The service that you specified is already registered as an internal service. All service definitions with the class SAG are reserved.

Choose another service name

EOC commands are not allowed while a UOW is being built.

Do not issue an EOC command before a UOW is committed. This message is for diagnostic purposes only.

The API field must be numeric.

Correct the field value.

The value of a field is incorrect.

Correct the field value.

Returned status of UOW is not valid.

Check the CONVID and UOWID in the Broker control block.

You cannot have UOW and non-UOW messages in the same conversation, that is, the same CONVID.

Check the application and correct the error.

You cannot have UOW and non-UOW messages in the same conversation, that is, the same CONVID.

Check the application and correct the error.

The Broker stub was initialized but had to be de-initialized because none of the shared library pointers (TCP, XTI or ADALNK) was available.

Check for any serious errors that may have caused library cleanup.

You cannot specify a DATA-ARCH to which a codepage applies without also specifying the codepage itself, using LOCALE-STRING.

Check the application and correct the error.

The locale string sent by a client/server or publish-and-subscribe component could not be mapped to a codepage by the broker's built-in locale string mapping. See Broker's Built-in Locale String Mapping.

Identify the locale string that could not be mapped to a codepage. The value of the LS keyword (LS=locale-string) in the broker trace may be helpful in identifying the erroneous locale string. Please use a valid locale string or define a new mapping in the broker attribute file. See the relevant attribute under locale-string for information on how to customize the mapping of locale strings to codepages.

The data/message retrieved after character conversion is larger than the supplied receive buffer. Conversion can increase the amount of your data. No data is provided in the receive buffer. The minimum buffer length required to receive the converted data is returned in the RETURN-LENGTH field of the API if API version 2 or above is used. The client or server should reread the message using a larger buffer with the required length.

For RPC components, the error can be ignored because the reread of the message is handled inside the RPC layer. Exception: for older Natural RPC versions it may be necessary to increase the MAX-BUFF parameter.

For ACI programming, see Error Cases under Using Send and Receive Buffers for information on how to respond to this error code.

The setting for security in the Broker kernel is different from the settings in one or more of the Broker stubs. Either the Broker kernel and all stubs must be configured to operate with security, or the kernel and all stubs must be configured to operate without security.

For ACI version 8 and above, this error can be caused by an application not setting the correct value of KERNELSECURITY in the EntireX Broker control block field; see KERNELSECURITY under Broker ACI Fields. The correct value is set automatically by the KERNELVERS command and this value must be maintained in the EntireX Broker control block field. If the application is unable or unwilling to perform the KERNELVERS command, configure the stub so that the security setting is consistent with the Broker kernel. See KERNELVERS under Broker ACI Functions and also Which EntireX Security Solution.

Ensure the security settings are consistent for Broker kernel and all the stubs.

When receiving a message, the Broker's CONVERSION exit determined that at least one character in the incoming message had no equivalent in the receiver's character set. The possibilities for this incomplete conversion:

• The sender's message contained a data value with no corresponding character in the sender's character set.

• All the sender's characters are valid, but at least one of them has no corresponding character in the receiver's character set.

If this condition occurs, the application should consider the received data to be potentially incomplete or missing.

Ensure that both sender and receiver are using the correct locale string and that all character values being sent have a corresponding character in the receiver's character set.

Wildcard ANY is currently not supported as valid topic name.

Use specific topic name.

The Broker ACI call FCT_SETSSLPARMS failed due to invalid specifications.

Check the 2nd parameter of this broker call and the length specified in the Broker ACI control block.

Only values of 0, 1 or 2 are valid encryption levels.

Correct the setting in the Broker ACI control block.

Entire Net-Work transport layer could not be initialized because the cslnk.so shared library could not be loaded.

Set the environment variable CSLNK to point to the cslnk.so library.

An inconsistency has been detected. The actual security setting to encrypt the payload buffer does not match the specification of the EL parameter in the current broker call.

Verify the EL parameter in the Broker ACI control block and/or verify the correct installation of the security exit.

The encryption settings of the EntireX client program do not match the settings in the Broker attribute file.

Check the ENCRYPTION-LEVEL specification in the Broker attribute file and adapt the settings to your client program (with respect to the security setting and/or the EL parameter).

For servers with API version below 6, a mismatch was found between the current security settings and the ENCRYPTION-LEVEL specification in the Broker attribute file.

Change the security settings:

• Activate / deactivate the security exit on the server side, or

• Amend the ENCRYPTION-LEVEL specification for this service in the Broker attribute file.

For servers with API version 6 or above, the setting of EL and the specification for ENCRYPTION-LEVEL in the Broker attribute file is not identical.

Either

• Correct the EL parameter (and security setting) in the server program, or

• Change the ENCRYPTION-LEVEL for this service in the Broker attribute file.

ACI function FCT_SETSSLPARMS was set for a non-SSL Broker connection.

Either change the BROKER-ID to use SSL or do not issue the ACI function FCT_SETSSLPARMS.

Compression is supported, but invalid option was specified.

Correct the compress option.

Compression of the data was attempted, but resulting size was equal to or greater than original data.

The compress option is turned OFF for this transmission of data; data will not be compressed.

During a decompress operation, failure occurred; it is most likely the result of insufficient memory for the process.

Increase available memory for process, if possible.

Error resulted from a compress or decompress operation, and is not accounted for by errors 0450 or 0451.

Save trace information. Contact Software AG support.

When decompressing a compressed data stream, the integrity of the data was compromised.

Save trace and data. Contact Software AG support.

Compression was requested but is not available

Retry the operation without compression.

A durable SUBSCRIBE request requires an available PSTORE, but the PSTORE is not available.

Option DURABLE is currently not permitted. Please consult your Broker Administrator.

Participant issues the function EOC, but unprocessed UOWs exist for the conversation. The EOC request is rejected.

Read the unprocessed UOWs first and issue function EOC afterwards.

Value NONE is not supported for the requested EntireX Broker function.

Correct application.

ALLOW-USER-SUBSCRIBE=NO was specified and therefore subscribe/unsubscribe must be performed by an administrator.

No action is required.

The publish and subscribe subsystem is not enabled due to missing definitions or license issues. Requested EntireX Broker function is rejected.

Contact your Broker Administrator.

The specified UOWID does not contain a unit of work

Please correct the UOWID.

Stub application did not provide a numeric value in the ERROR-CODE field in Broker control block while making a REPLY_ERROR function call.

Send a valid numeric value in the ERROR-CODE field of the Broker control block.

Stub application provided an invalid error code in the Broker control block, while making REPLY_ERROR function call. User-defined error codes should not begin with number 8, and should contain only numeric values.

Make sure that error code in the Broker control block does not start with '8' and contains only numerals.

Receiving application did not provide its codepage information in LOCALE-STRING field of the Broker control block.

Supply codepage information in the LOCALE-STRING field of the Broker control block. If you want the broker to supply default codepage information, specify MAP=YES in CONVERSION attribute under DEFAULTS=SERVICE section.

Sender application did not provide codepage information in LOCALE-STRING field of the Broker control block.

Supply codepage information in the LOCALE-STRING field of the Broker control block. If you want the broker to supply default codepage information, specify MAP=YES in CONVERSION attribute under DEFAULTS=SERVICE section.

The value for RETURN-LENGTH was truncated. This occurs if the value is greater than 99,999,999 and ACI version 8 or below is used.

Upgrade to ACI version 9 or above.

There are still open units of work that have not been committed, cancelled, or backed out yet. The ACI function DEREGISTER was not completed successfully.

Finish the open units of work first before calling DEREGISTER.

The supplied value is invalid. Broker supports compression types GZIP and ZLIB.

Correct the program to supply a valid value.

The amount of message extension data to be returned is greater than the value specified under EXTENSION-RECEIVE-LENGTH. Field EXTENSION-RETURN-LENGTH is set to amount of extension data still to be returned.

Set EXTENSION-RECEIVE-LENGTH to value of EXTENSION-RETURN-LENGTH and receive the message again (OPTION=LAST) to receive the remaining associated extension data.

Command and Information Services were unable to add a command log filter as the specified filter was already active.

Specify a filter that is not already active.

Command and Information Services were unable to delete a command log filter as the specified filter did not exist.

Specify a filter that does exist.

An application has specified a protected unit of work ID in an API request. Protected unit of work IDs are 0000000000000000 and 0000000000000001.

Specify a non-protected unit of work ID.

The user is not authorized to shut down EntireX Broker.

A security violation has occurred. This message and the related user ID are written to the Broker log.

A mismatch was detected between settings of service and user regarding the mode chosen to send or receive ARF data. The single conversation mode (one conversation per service) has to be requested by the user before sending or receiving ARF data. It is not possible to change the mode if there are still conversations active that have been created with the old mode.

ARF can be configured to use or not to use the ETBSCONV feature (single conversation mode). We strongly recommend using this feature, but it requires a service without any conversations created with the old mode. If the ETBSCONV feature was specified and conversations still exist, these conversations have to be consumed before you change to single conversation mode.

An unsupported function (UNDO or DELETE) has been issued.

Check the program and correct the error.

An unsupported value has been specified for the CONV-ID field.

This is a user error. Check the program and correct the error.

An unsupported value has been specified for the WAIT operand.

This is a user error. Check the program and correct the error.

An unsupported value has been specified for the OPTION field.

This is a user error. Check the program and correct the error.

An error has occurred in the EntireX Broker Services protocol adapter. Depending on the protocol in use, it may be an SNA sense code or an MQM reason code.

Obtain the error code from the first 8 bytes of the error message (xxxxxxxx) or the ADAPTER-ERROR field. Then refer to the appropriate SNA or MQM documentation to determine the actual error.

An unsupported value has been specified for CLASS or SERVICE, e.g., APPC is not specified for CLASS.

This is a user error. Check the program and correct the error.

No action is required.

No CONV-ID, or an incorrect CONV-ID, was specified for the DEREGISTER function.

This is a user error. Check the program and correct the error.

OPTION=ATTACH was specified for a function that is not a REGISTER, DEREGISTER, or RECEIVE function.

Check the program and correct the error.

A Remote Attach Manager program has issued a non-blocked RECEIVE request with WAIT=NO, but there are no pending attach requests.

This is an informational message.

An ACI RECEIVE request has been issued without a valid CONV-ID value. All ACI RECEIVE requests must specify a CONV-ID value.

Check the program and correct the error.

An ACI RECEIVE request has been issued by a client program that specified CONVID=OLD or ANY while an MQI MODEL queue was in use.

Change the program to use a specific, existing CONVID, or remove the REPLYTOQ specification from the directory entry.

A SEND request has been issued with an invalid combination of MSGTYPE=, WAIT= and CONFIRMATION operands. For example, specifying WAIT=YES when sending a DATAGRAM or a REPLY type message is invalid.

Correct the program logic.

A server program attempted to issue a SEND request with CONVID=NONE, which is not allowed. Server programs must use a specific CONVID when issuing a SEND.

Correct the program logic.

A server program attempted to issue a SEND request with MSGTYPE=DATAGRAM or REQUEST, which is not allowed. Server programs are allowed to issue SEND MSGTYPE=REPLY only.

Correct the program logic.

A client program attempted to issue a SEND request with MSGTYPE=REPLY, which is not allowed. Client programs are allowed to issue SEND MSGTYPE=REQUEST or DATAGRAM only.

Correct the program logic.

A request was issued with OPTION=SYNC and WAIT=YES. It is not possible to issue a "blocking" request (WAIT=YES) within a unit of work.

Correct the program logic.

A SYNCPOINT request was issued without a valid OPTION= specification. Either OPTION=COMMIT or OPTION=BACKOUT must be specified with the SYNCPOINT function.

Correct the program logic.

A client program must use a specific MSGID when issuing a RECEIVE request with CONVID=ANY, NEW, or NONE.

Correct the program logic.

An ACI request was received that has specified a value for one of the unit of work fields.

Programmer: Ensure no unit of work fields have been specified in the ACI request. If API Version=3 has been specified in the Broker control block (ETBCDEF.H), ensure that the unit of work fields have all been cleared.

An internal buffer shortage has occurred that prevents the function from executing.

Review the JES JOBLOG and external trace for error messages that might give additional information on the problem.

A Remote Attach Manager has issued a RECEIVE request for a TP that is not currently REGISTERED to its SERVICE-ID.

Modify the Remote Attach Manager program to REGISTER this tpname.

A Remote Attach Manager has issued a REGISTER request for a TPNAME that already issued a REGISTER.

A TPNAME must be unique and can be registered under one and only one SERVICE-ID.

A request was received using the ATTACH-MANAGER DDM, but the request was not a REGISTER, RECEIVE, or DEREGISTER.

Correct the Remote Attach Manager program and retry. The external trace may contain additional information for debugging.

EntireX Broker Services have been shut down by the computer operator.

No action required; normal processing continues.

A Remote Attach Manager has issued a verb that is invalid.

The message text will contain the function and missing value. Correct the request and retry.

A REGISTER request from a Remote Attach Manager is being rejected because of conflicts with Control Operator Interface definitions (RESTRICT-PARTNERS=PROFILE has been specified).

Add the TPNAME in the message to the appropriate local LU definitions and retry the Remote Attach Manager program.

An Attach Manager RECEIVE was issued, but the specified servername has been stopped by an operator command. The message contains the actual server name.

The Remote Attach Manager Dispatcher program may be restarted after using the RESUME, D6 servername operator command to reactivate the servername.