SL_CALL_SETUP_REQ primitive

Purpose

Request the establishment of an outbound call.

Requirement

Mandatory for common channel signaling processes. The primitive is not used by exchange data link signaling processes.

Library

The signaling interface library (libsl.a).

C syntax

typedef struct {
                SL_ID id;
                int iseq_no;
                pid_t pidCHP;
                SL_PRIMITIVE_TYPE Command;
                SL_REQUEST_PARM_ST Parms;
} SL_REQUEST_ST;
...
typedef union {
...
                struct _call_setup_request_st {
                    size_t sizetLength;
                    SL_CALL_REF slCallReference;
                    int pause;
                    int ring_wait;
                    int ring_time;
                    int iChannelNo;
                    int iVpackNo;
                    int ifdBearerChannel;
                    SL_BOOL ChannelGroupSet [SL_MAX_CHANNEL_GROUP];
                    char phone_num[SL_PHONE_NUM_LEN];
                    SL_APPL_INFO_ST slApplInfo;	
                } call_setup_request_st;
...
} SL_REQUEST_PARM_ST;

Description

The SL_CALL_SETUP_REQ primitive is sent by the channel process to the signaling process to request the establishment of an outgoing call. On receipt of the SL_CALL_SETUP_REQ primitive the signaling process should setup a call as requested. When call setup is complete, or the call attempt has failed, the signaling process should send back the SL_CALL_SETUP_CNF primitive, with the ReplyCode set to indicate the success of the call.

The channel process completes the parameters in the SL_CALL_SETUP_REQ primitive.

Blueworx Voice Response requires that common channel signaling processes implement channel negotiation. The channel process sets the iChannelNo field to SL_UNDEFINED_CHAN and the iVpackNo field to SL_UNDEFINED_VPACK. The signaling process is responsible for allocating the actual channel used for the call. The signaling process is responsible for retrying the call if the first attempt is unsuccessful. For example, if an incoming call is offered by the network on the same channel that the signaling process used to attempt the outgoing call setup, the signaling process is responsible for managing the collision. The actual channel and trunk used for the call are returned in the SL_CALL_SETUP_CNF primitive.

The state table can restrict the trunk or channel used for an outgoing call, by specifying which channel groups are acceptable. The state table does this by setting a system variable, which is passed to the signaling process in the ChannelGroupSet parameter. The signaling process is responsible for selecting a channel that is a member of one of the specified channel groups. The sl_query_channel_group() subroutine allows the signaling process to query the channel group for any channel. A typical use of channel groups might be to have trunks in one channel group for incoming calls, and trunks in a second channel group used for outgoing calls. Your organization may, for example, use different service providers for inbound and outbound trunks.

Corresponding state table action

The SL_CALL_SETUP_REQ primitive and the matching SL_CALL_SETUP_CNF correspond to the MakeCall state table action. See the Blueworx Voice Response for AIX: Application Development using State Tables information.

Parameters

id: Eye-catcher that identifies the structure as containing a request primitive. Must be set to SLID_REQUEST_ST.
iseq_no: The sequence number of the primitive. This field must be set to 0 when the primitive is sent to Blueworx Voice Response; the actual sequence number is allocated by Blueworx Voice Response, and is available to the sender on return from sl_send_request(). The field is set when the primitive is received from Blueworx Voice Response by the signaling process.
pidCHP: The process id of the channel process. The signaling process should use this value to set the pidCHP field of the corresponding SL_CALL_SETUP_CNF primitive. Because the process id of the channel process is also required when sending SL_CALL_TERMINATE_IND, the signaling process should store this value together with the call reference for later use.
Command.id: The primitive that the structure contains. Must be set to SL_CALL_SETUP_REQ.
Parms.call_setup_request_st.sizetLength: Must be set to sizeof(struct _call_setup_request_st).
Parms.call_setup_request_st.slCallReference: The call reference that identifies the call. This field must be set to SL_CALL_REF_NULL when the primitive is sent to Blueworx Voice Response; the actual call reference is allocated by Blueworx Voice Response, and is available to the sender on return from sl_send_request(). The field is set when the primitive is received from Blueworx Voice Response by the signaling process. Because the call reference uniquely identifies calls, the signaling process should store this value together with the value of pidCHP for future use.
Parms.call_setup_request_st.pause: This field contains the value specified in the Pause parameter of the MakeCall state table action. The value specified by the state table may be ignored by common channel signaling processes.
Parms.call_setup_request_st.ring_wait: This field contains the value specified in the Ring Wait parameter of the MakeCall state table action. This specifies how long to wait for ringback tone after sending digits.
This time is usually part of the protocol specification for common channel signaling protocols. The value specified by the state table may be ignored by common channel signaling processes.
Parms.call_setup_request_st.ring_time: This field contains the value specified in the Ring Time parameter of the MakeCall state table action. This specifies how long to wait while the dialed number rings.
This maximum time to wait for the called party to answer is usually part of the protocol specification for common channel signaling. The signaling process should return SL_REPLY_NO_ANSWER, if the value specified by the state table is less than the network maximum ring time and the call is not answered. If the value specified by the state table is greater than the network maximum ring time, it may be ignored by common channel signaling processes, which should return SL_REPLY_NO_ANSWER when the network clears the call.
Parms.call_setup_request_st.iChannelNo: Identifies the channel associated with the call. This is set to SL_UNDEFINED_CHAN if the target signaling process supports channel negotiation. This indicates that the signaling process is responsible for allocating the channel for the call.
Parms.call_setup_request_st.iVpackNo: Identifies the trunk associated with the call. This is set to SL_UNDEFINED_VPACK if the target signaling process supports channel negotiation. This indicates that the signaling process is responsible for allocating the trunk for the call.
Parms.call_setup_request_st.ifdBearerChannel: The file descriptor for the bearer channel. This file descriptor must be provided by the channel process, when it sends the SL_CALL_SETUP_REQ primitive. The file descriptor should be ignored by the signaling process. The file descriptor is not available for use by the signaling process: using it causes unpredictable results.
Parms.call_setup_request_st.ChannelGroupSet: Specifies which channel groups are acceptable for this call. This field contains the value specified by the application in the system variable System: Call: Permitted channel groups (SV178). The permitted channel groups are represented as an array of BOOL. Because Blueworx Voice Response numbers channel groups from 1 (SL_MIN_CHANNEL_GROUP_ID), the element ChannelGroupSet[0] is unused. For the remaining elements: ChannelGroupSet[n] is set to TRUE if channel group n is acceptable for this call, and to FALSE if it is not.
Parms.call_setup_request_st.phone_num: This field contains the value specified in the Phone Number parameter of the MakeCall state table action. This specifies the phone number to call.
The maximum length of phone number supported by Blueworx Voice Response is SL_NUM_SZ-1 digits. The phone_num field is longer than this to allow for future expansion.
Parms.call_setup_request_st.slApplInfo: Contains both the length of the call information tag string (including the null terminator '\0') and the call information tag string array itself. The string is used to pass information between state tables and the signaling process. For more information see SL_APPL_INFO_ST data structure