CPI-C Reference

Naming Conventions--Calls, Characteristics, Variables, and Values

Pseudonyms for the actual calls, characteristics, variables, states, and characteristic values comprising CPI Communications are used throughout this book to enhance understanding and readability.

Where possible, underscores (_) and complete names are used in the pseudonyms. Any phrase in the book that contains an underscore is a pseudonym. For example, Send_Data is the pseudonym for the program call CMSEND, which is used by a program to send information to its conversation partner.

This book uses the following conventions to aid in distinguishing between the four types of pseudonyms:

• Calls are shown in all capital letters. Each underscore-separated portion of a call's pseudonym begins with a capital letter. For example, Accept_Conversation is the pseudonym for the actual call name CMACCP.

• Characteristics and variables used to hold the values of characteristics are in italics (for example, conversation_type) and contain no capital letters except those used for abbreviations (for example, TP_name).

  In most cases, the parameter used on a call, which corresponds to a program variable, has the same name as the conversation characteristic. Whether a name refers to a parameter, a program variable, or a characteristic is determined by context. In all cases, the value used for the three remains the same.

• Values used for characteristics and variables appear in all uppercase letters (such as CM_OK) and represent actual integer values that will be placed into the variable. For a list of the integer values that are placed in the variables, see Table 60 in Appendix A. "Variables and Characteristics".

• States are used to determine the next set of actions that can be taken in a conversation. States begin with capital letters and appear in bold type, such as Reset state. Bold is also used to denote the Backout-Required condition.

• Queues are used to group related CPI Communications calls. Queue names begin with capital letters. The parts of a queue name are connected with a hyphen.

As a complete example of how pseudonyms are used in this book, suppose a program uses the Set_Return_Control call to set the conversation characteristic of return_control to a value of CM_IMMEDIATE.

• Set_Return_Control (CMSRC) contains the syntax and semantics of the variables used for the call. It explains that the real name of the program call for Set_Return_Control is CMSRC and that CMSRC has a parameter list of conversation_ID, return_control, and return_code.

• Appendix A. "Variables and Characteristics" provides a complete description of all variables used in the book and shows that the return_control variable, which goes into the Set_Return_Control call as a parameter, is a 32-bit integer. This information is provided in Table 62.

• Table 60 in Appendix A. "Variables and Characteristics" shows that CM_IMMEDIATE is defined as having an integer value of 1. CM_IMMEDIATE is placed into the return_control parameter on the call to CMSRC.

• Finally, the return_code value CM_OK, which is returned to the program on the CMSRC call, is defined in Appendix B. "Return Codes and Secondary Information". CM_OK means that the call completed successfully.

Notes:

1. Pseudonym value names are not actually passed to CPI Communications as a string of characters. Instead, the pseudonyms represent integer values that are passed on the program calls. The pseudonym value names are used to aid readability of the text. Similarly, programs should use translates and equates (depending on the language) to aid the readability of the code. In the above example, for instance, a program equate could be used to define CM_IMMEDIATE as meaning an integer value of 1. The actual program code would then read as described above--namely, that return_control is replaced with CM_IMMEDIATE. The end result, however, is that an integer value of 1 is placed into the variable.

2. Section "Programming Language Considerations" in Set_Return_Control (CMSRC) provides information on system files that can be used to establish pseudonyms for a program.