This group of functions facilitate dataIn and dataOut commarea processing. All the functions work with the format described in
CALLRULE – Call a Rule. Generally, these functions do not validate memory pointers passed as parameters.
Appendix A, SDK (C/C++) and SDK (Java) Error Reason Codes for a list of error reason codes issued in relation to the SDK (C/C++).
cliProc is the main SDK (C/C++) function. It accepts specific operation requests and the meaning of most cliProc parameters depends on the specifics of the request.
|
Application-supplied session work area. The SDK (C/C++) client uses this area to store all session related internal data. For the SDK (C/C++) client to function properly, the application must not modify contents of this area.
|
|
|
These values are in ASCII for Open Systems, and in EBCDIC for z/OS. The strings do not have to be zero-terminated. To determine what operation is requested, the SDK (C/C++) client compares the supplied request name to these names until the match is found. If the request name is not one of these, cliProc fails with CLI_INVREQUEST (2) as return code.
|
Pointer to the operand. The meaning of this parameter varies depending on the specific request (that is, the value of the operation cliProc parameter, described above).
|
|
Pointer to the operation parameters. The meaning of this parameter varies depending on the specific request (that is, the value of the operation cliProc parameter, described above).
|
|
|
|
|
|
Pointer to the memory area where the result of the operation is to be stored. The nature of the result depends on the specific request (that is, the value of the operation cliProc parameter, described above).
|
|
Pointer to the memory area where return code of the request is to be stored. If the request succeeds, CLI_SUCCESS (0) is returned, if the request fails, the value depends on the specific request (that is, the value of the operation cliProc parameter, described above).
|
|
For some values of operation, some of these parameter are ignored. In this case, it does not matter what the parameter contains. This is different from setting a parameter to NULL, which has a specific meaning for that parameter.
|
All the requests accepted by cliProc are session-related. Sessions are distinguished by the
session parameter of cliProc.
session points to application-provided storage that the SDK (C/C++) client uses to store all the data related to a particular session. The structure of this storage is internal and the application must not modify data in storage. Type CLI_SESSION is provided to declare or allocate variables large enough to hold all internal session data.
STARTSS properly formats the session area and the other operations assume that the area is formatted correctly. For all cliProc calls except STARTSS, if
session was not previously passed to STARTSS or is corrupt, the behavior of the SDK (C/C++) client is undefined. The SDK (C/C++) client checks an eyecatcher area in the
session area and, if the eyecatcher is corrupt, the operation fails with a CLI_SESSINVALID (199) error reason code. Use this error reason code as an indication of memory misuse when debugging the application.
Generally, cliProc does not perform memory accessibility checks for pointers that the application supplies. However, there are a few exceptions from this rule, as described in the cliProc request specifications that follows.
|
If two calls to STARTSS with the same session parameter are issued one right after the other, the first session becomes inaccessible because all the internal SDK (C/C++) data for that session is lost. To avoid this, always issue a STOPSS or a RESETSS before issuing another STARTSS on the same session area.
|
Use the session parameters string (params) to define various session behavior aspects. There are a number of parameters that are specific for the SDK (C/C++). These are (names are case insensitive):
CLIHOST, CLIPORT, and CLINODE are used to identify the TIBCO Object Service Broker monitor process (Windows or Solaris) or the Execution Environment (z/OS) on the network. You can do this in one of these two ways:
Make sure that your session parameter string contains either the CLIHOST and CLIPORT parameters, or the CLINODE parameter. Otherwise, STARTSS fails with a CLI_INVNODE (193) error reason code.
CLIENDIAN provides a way to override the application endian type for a session. This parameter affects the external representation of MAP table fields with numeric internal syntaxes and the “*” external syntax. If CLIENDIAN is not specified, the endian type natural for the SDK (C/C++) client platform is selected. The
session area is formatted to represent a session for subsequent cliProc calls. Even if the STARTSS call fails, the area can be used in subsequent cliProc calls (all calls except SESSACTIVE and GETENDMSG fail with a CLI_CALLOUTOFSEQ (36) error reason code). Do not call a STARTSS passing
session area pointer that represents another active session, because the information about it is overwritten.
If you omit a parameter, STARTTR uses session default value specified in the session parameter string at STARTSS time. These session defaults are set by the BROWSE, TEST, SEARCH, and LIBRARY session parameters. For more information on these, refer to
TIBCO Object Service Broker Parameters.
If the maximum allowed number of transactions are already running in the session, the operation fails with TOOMANYTRANS (106) error reason code. Refer to
TIBCO Object Service Broker Parameters for information on the TRANMAXNUM Execution Environment parameter, which sets the maximum value.
|
|
|
|
|
|
|
|
Rules call string of the following form: 'RULENAME(PARAM1, PARAM2,…,PARAMn)' It must be prefixed by a two-byte string giving its length, exclusive of the length of the prefix. The string must be in the session SDK (C/C++)/SDK (Java) code page. The endian type of the length prefix is the same as the endian type of the SDK (C/C++) client platform. The maximum allowed length of the call string (excluding the length prefix) is 514 (CLI_MAXRULEEXPRLEN in oscli.h).
|
|
|
|
|
|
|
Length (two bytes, unsigned integer, the SDK (C/C++) client platform endian type) of the whole rules return value in textual form (length prefix and terminating zero are excluded). If the operand is NULL, no length is written.
|
|
Points to a memory area where the error reason code (four bytes) is to be placed if the operation fails. If the operation succeeds, the area is filled with the rules return value in textual form. The maximum number of bytes written to retData is passed through the operand parameter. The return value is in the session SDK (C/C++)/SDK (Java) code page. It is prefixed by two bytes stating its length and has a terminating zero byte at the end. The endian type of the length prefix is the same as the endian type of the SDK (C/C++) client platform.
|
|
|
CALLRULE performs a rules call. Rules name and parameters are supplied in a textual form “RULENAME(PARAM1, PARAM2,…,PARAMn)”. The maximum length of this string is 514 (CLI_MAXRULEEXPRLEN) excluding the length prefix. If a longer string is passed, CALLRULE fails with a CLI_RULEEXPRTOOLONG (3090) error reason code. If
params is NULL, CALLRULE fails with a CLI_NORULENAME (96) error reason code.
The rules return value is converted to text and placed in the memory pointed to by the
retData parameter. The
operand parameter is used as an In/out parameter. An application uses it to pass the number of bytes available to store the rules return value and the SDK (C/C++) client uses the parameter to return the length of the whole return value in text form, regardless of possible truncation. The returned length does not include the two-byte length prefix and terminating zero. To determine whether truncation occurred, the application can compare the resulting value to the value of the length prefix of the string in
retData buffer.
If the rule does not return a value, an empty string is stored in retData. An empty string in this case is represented by three zero bytes, two for the length prefix, one for the terminating zero.
CALLRULE uses the dataIn and dataOut commareas for binary data exchange between the application and the rule. The format of a commarea is as follows:
If dataIn or
dataOut does not reside in accessible memory, CALLRULE fails with the appropriate error reason code. The dataIn memory must be accessible for reading and dataOut for reading and writing.
The TIBCO Object Service Broker Execution Environment creates a copy of dataIn and makes the pointer to the area available to the rule through the APIINHANDLE field of @SESSION(0). For dataOut, the Execution Environment allocates memory for the whole area and copies the area header. A pointer to dataOut is made available through the APIOUTHANDLE field of @SESSION(0). For more information about the @SESSION table, refer to
TIBCO Object Service Broker Shareable Tools.
Access to dataIn and dataOut using MAP tables is always granted by the system and MAP tables can be used without @MAP registration of the dataIn and dataOut addresses. dataIn is accessible for reading and dataOut for reading and writing. For more information about MAP tables, refer to
TIBCO Object Service Broker Managing Data.
When a rule successfully completes, contents of the dataOut are transferred back from the Execution Environment to the application memory. Consider reducing the number of bytes your rule transmits to the application. You do this by properly reformatting the dataOut header, before transmitting data back, the Execution Environment reevaluates the dataOut header to determine the correct number of bytes to send back to the application.
STOPTR commits or rolls back changes and stops the transaction active within a given session. The current transaction is destroyed and the session transaction nesting level is decremented even if STOPTR fails.
All other error reason codes mean that the session shutdown sequence did not complete properly (for instance, network connection was lost during the session shutdown), but the session became inactive anyway.
RESETSS forcefully closes the session by dropping the session connection as opposed to an orderly shutdown by STOPSS. The session does not have to be active for the call to succeed. When a connection is dropped, the Execution Environment generates an error message, and closes the session. All uncommitted data changes are lost.
If session is processed by STARTSS and is not modified directly by the application, RESETSS does not fail. If
session was not previously passed to STARTSS or became corrupt, the operation can fail with CLI_SESSINVALID (199). Refer to
cliProc for information about session area validity checks.
|
|
|
|
|
|
|
Points to a memory area where the rules end message is to be placed. The end message has a two-byte length prefix and a terminating zero. The endian type of the length prefix is the same as the endian type of the SDK (C/C++) client platform. The maximum length of a TIBCO Object Service Broker rules end message is 148 (CLI_MAXENDMSGLEN in oscli.h), therefore to accommodate an end messages, the application must provide a buffer of 151 bytes. The rules end message is in the session SDK (C/C++)/SDK (Java) code page.
|
|
|
GETENDMSG retrieves the most recent rules end message. The session does not have to be active for the call to succeed. If no CALLRULE was issued within the session or rules did not generate an end message, an empty string (three bytes of zeroes) is returned.
If session is processed by STARTSS and is not modified directly by the application, GETENDMSG does not fail. If
session was not previously passed to STARTSS or became corrupt, the operation can fail with CLI_SESSINVALID (199). Refer to
cliProc for information about
session area validity checks.
It is possible for a TIBCO Object Service Broker session to become inactive any time after starting (due to network problems, Execution Environment abnormal terminations, and so on).
When that happens, STARTTR, STOPTR, CALLRULE, and STOPSS operations on this session fail with an appropriate error reason code. In addition, appropriate changes to the
session area are made to indicate that the session is no longer active, so that subsequent STARTTR, STOPTR, CALLRULE, and STOPSS operations fail with a CLI_CALLOUTOFSEQ (36) error reason code. Use a SESSACTIVE cliProc request to determine whether the session is still active. If the session abends or is stopped by STOPSS or by RESETSS, SESSACTIVE returns 0 in the
retData area.
If session is processed by STARTSS and is not modified directly by the application, SESSACTIVE should not fail. If
session was not previously passed to STARTSS or became corrupt, the operation can fail with CLI_SESSINVALID (199). Refer to
cliProc for information about
session area validity checks.
This function indicates the SDK (C/C++)/SDK (Java) code page, that is, the code page that your application expects to use to communicate with TIBCO Object Service Broker sessions.
|
Address of the SDK (C/C++)/SDK (Java) code page name. The code page name is expected to be 16‑byte blank-padded text. No terminating zero is required. The code page name is expected to be in ASCII. The valid values for this field are the code page names shown in TIBCO Object Service Broker National Language Support.
|
|
•
|
WIN‑1252 is recommended for use in clients that do not depend on TIBCO Object Service Broker code pages; it supports all TIBCO Object Service Broker code pages.
|
•
|
ISO8859‑1 works only with code pages that do not support the euro sign.
|
•
|
ISO8859‑15 works only with code pages that support the euro sign.
|
|
The code page setting determines the code page of certain cliProc IN/OUT parameters as well as the external representation of MAP table fields with “*” external syntax and textual internal syntaxes.
cliSetCodepage stores, without validation, the code page name for future STARTSS cliProc requests that have no overriding code page specified. If the code page is not supported by TIBCO Object Service Broker, STARTSS fails with a CLI_UNSUPPCODEPAG (161) error reason code.
cliSetCodepage is thread safe and can be called at any time by any application thread. However, due to the fact that cliSetCodepage deals with the global data of the SDK (C/C++) client, some contention can occur if many threads are issuing cliSetCodepage or STARTSS cliProc requests that have no overriding code page specified, at the same time. If you need to simultaneously start sessions with varying code page settings, using the STARTSS
operand parameter is a better choice because it does not lead to resource access synchronization by the SDK (C/C++) client.
Pointer to the beginning of the created commarea (to the count field of the header – refer to the commarea format description in
CALLRULE – Call a Rule), or NULL if the memory allocation failed.
This function formats a memory area according to the commarea format specifications, as supplied through the
count and
segmentSizes parameters.
Behavior of this operation is undefined if the area memory area is not large enough to hold the header part of the commarea. Allocation and deallocation of the
area memory is the responsibility of the application. Do not use cliCommDelete to deallocate the
area memory.
Behavior of this operation is undefined if the area memory area is not large enough to hold the header part (12 bytes for the areas with one segment) of the commarea. Allocation and deallocation of the
area memory is the responsibility of the application. Do not use cliCommDelete to deallocate the
area memory.
If the area memory does not comply to the commarea format rules (refer to
CALLRULE – Call a Rule), the behavior is undefined.
If the segment does not exist (that is, the count field in the header is less than or equal to
segmentNum), this function returns 0.
If the area memory does not comply to the commarea format rules (refer to
CALLRULE – Call a Rule), the behavior is undefined.
If the area memory does not comply to the commarea format rules (refer to
CALLRULE – Call a Rule), the behavior is undefined.