Throughout this book, the names of actual program calls, messages, parameters, call profile characteristics, variables, and parameter or characteristic values that make up the CallPath Services API are represented by pseudonyms. The pseudonyms are used to simplify understanding and to aid readability. For example, the program call STLMAKE is used by a program to establish a telephone call; its pseudonym in this book is Make_Call.
Where possible, pseudonyms are made up of complete names. If a pseudonym is composed of more than one word, the words are connected with an underscore (_). Any phrase in the book that contains an underscore is a pseudonym.
To aid in distinguishing the various types of pseudonyms, the following naming and notational conventions are used:
Program calls and Set Program Calls have both an actual program call name and a pseudonym. Actual program call names are made up entirely of capital letters. The first three characters of all CallPath Services program call names are STL to indicate that the program calls are associated with the CallPath Services API. For example, the program call STLRCV is used by a program to receive messages.
The pseudonym for STLRCV is Receive. Pseudonyms for program calls begin with a capital letter, as does each portion of the pseudonym that follows an underscore. For example, Initialize_Call_Profile is the pseudonym for the actual program call name of STLINIT.
Parameters on program calls contain no capital letters except those used for abbreviations and appear with a common highlight style (for example, call_profile_ID).
Call profile characteristics contain no capital letters except those used for abbreviations and appear with a common highlight style (for example, switch_ID).
Variables are defined by a program and are used to hold the values of parameters or characteristics. For example, party_one is one of the parameters on the Make_Call program call. When a program issues a Make_Call program call, it must specify a variable that contains the value required by the party_one parameter. The name of the variable could be party_one, P1, or anything else the program wishes to use. Variables contain no capital letters except those used for abbreviations and appear with a common highlight style (for example, party_two).
In many cases, the parameter used on a program call, which corresponds to a program variable, has the same name as a call profile characteristic. Whether a name refers to a parameter, a program variable, or a call profile characteristic is determined by context. In all cases, the value used for the three remains the same.
To indicate that a variable has been set to a particular value, the book's convention is to either say so explicitly or use "function" notation. For example, a party_specification of STL_DIRECTORY_NUMBER may also appear as party_specification (STL_DIRECTORY_NUMBER).
Values used for parameters, characteristics, and variables represent actual integer values that are to be placed into the variable. All values appear with a common highlight style (for example, STL_MONITOR_DIRECTORY_NUMBER). The pseudonyms begin with the STL prefix to indicate that the values are associated with the CallPath Services API. For example, STL_OK is the pseudonym for an actual integer value that can be returned in the variable that represents the return_code parameter on program calls.
For a list of the integer values that are placed in the variables, see the CallPath Server Toolkit Programmer's Guide and Reference.
Messages are represented by both an informal pseudonym and by a formal pseudonym. A formal pseudonym represents a parameter or variable value. For example, the informal pseudonym for the message that indicates to a program that a party has become an active participant in a telephone call is Call_Connected. The formal pseudonym for Call_Connected is STL_CALL_CONNECTED_MSG.
When a program issues a Receive program call and is returned a Call_Connected message, the program is informed that the message is a Call_Connected message by means of the message_code parameter on Receive. The program, when it issues the Receive program call, provides a variable to represent the message_code parameter. The CallPath Services subsystem places into the supplied variable a value that indicates the message that is being returned in another variable on the program call. In this example, where a Call_Connected message is returned to the program, the pseudonym associated with the returned message_code parameter is STL_CALL_CONNECTED_MSG and represents the integer value that is actually placed into the variable. (In this case, the integer value is 1.)
The informal pseudonyms associated with messages begin with a capital letter, as does each portion of the name that follows an underscore. For example, Call_Alerting is used in place of the pseudonym for the message_code parameter value of STL_CALL_ALERTING_MSG. STL_CALL_ALERTING_MSG, in turn, is used in place of the actual message code value (in this case, an integer value of 0). As shown, formal pseudonyms associated with messages appear with a common highlight style (for example, STL_CALL_ALERTING_MSG).
To provide a complete example of how pseudonyms are used in this book, suppose a program uses the Set_Make_Call_Forward_Override program call to modify the call profile characteristic of make_call_forward_override to a value of STL_FORWARD_OVERRIDE.