IBMTromboneCall

This state table encapsulates the code needed to create the trombone between a caller and a third party in a single call. This state table is called by the user’s application, along with a number of parameters using the InvokeStateTable action. The code is encapsulated in this way to allow it to be used in a similar way to other telephony actions without having to be concerned about the details of performing the trombone.

If the trombone is set up successfully, this state table will not return until either one of the parties hangs up, or the caller terminates the trombone by dialing a specified number using DTMF keys.

If the trombone operation fails, the state table exits immediately with a status code (and return edge) that indicates what the problem is.

For details of the communications that this state table performs with IBM_TromboneCustom_Server, see How tromboning works.

The source code is commented to help make customization easy. The ability to log data and turn background music on and off has been provided in two separate state tables (IBMTromboneLog and IBMTromboneMus) that you can invoke to prevent this state table becoming too complex and cluttered.

Parameters

String phone_number (40 character max):

The number to dial for the outgoing part of the trombone (see the definition of phone_number in the MakeCall state table action for details).

String format (50 characters max):

The format string for the number to dial for the outgoing part of the trombone (see the definition of format in the MakeCall state table action for details).

String log_filename (64 characters max):

If this is blank, no event logging is performed. If you supply a filename, the IBMTromboneLog state table logs trombone calls and their results to an event log with that filename.

String user_data (64 characters max):

Some user-defined data for simple communications from the IBMTromboneCall state table to the IBMTromboneOut state table.

This may be used, for example, to reference a prompt to be played as an announcement to the third party before the trombone operation connects the third party to the caller.

String out_stbl_name (16 characters max):

The name of the state table to use for the outbound part of the trombone operation. If this is blank, the default state table IBMTromboneOut is used.

String out_stbl_entry (16 characters max):

The entry point to use within the state table used for the outbound part of the trombone operation. If this is blank, the default label of begin is used.

String end_on_DTMF (64 characters max):

If this is blank, the state table ignores any DTMFs it receives from the caller during the trombone operation.

If this parameter contains a number (one or more digits), it terminates the trombone operation on receiving the given number from the caller. When the trombone terminates, the third party is disconnected and the caller remains connected to Blueworx Voice Response.

If this parameter is set to -, the trombone terminates when it receives any DTMF from the caller. Valid DTMF digits are 0 to 9, *, and #.

String music_on_hold (64 characters max):

If this is blank, the state table doesn’t play any background music to the caller while the trombone operation is being set up.

If this parameter contains a string, the state table tries to play background music (simulating music on hold) to the caller while the trombone is being set up. This parameter defines the name of the music file to play.

See Background music for details of how to setup and configure background music.

If background music is not configured on Blueworx Voice Response, and you try to play background music during the trombone operation, that operation will fail.

Number call_status (this value is returned):

The returned status of the trombone operation.

If the value is zero, the trombone operation was successful and was terminated by either the third party hanging up, or the caller requesting a disconnection by dialling the correct DTMF sequence.

If this value is non-zero, the trombone operation did not complete successfully. Table 1 shows the meanings of the possible call_status values. Valid values are any given in the table except those between 221 and 227.

This state table returns different edges depending on where in the range of possible values the call_status (also defined in Table 1). This allows the general area of the problem to be determined immediately by the return edge of the InvokeStateTable action that called IBMTromboneCall.

Table 1. Return values from the IBMTromboneCall state table (call_status).
This table lists the Return Edge values and the corresponding Error Description for particular Call Status values.
Return Edge	Call Status	Error Description
0	0	Trombone function request was successful.
1	Bad return code from the MakeCall request to the third party by the IBMTromboneOut state table (assuming that the IBMTromboneOut and IBMTromboneCall state tables have not been customized to alter these values)
	1	Invalid phone number
	2	Invalid format string
	3	Phone busy
	4	Network busy
	5	No answer
	6	Outbound line problem
	7	No line available
	8	Channel active
	9	Unexpected tone
2	Bad return code from the IBMTromboneOut state table, other than from the MakeCall request (assuming that the IBMTromboneOut and IBMTromboneCall state tables have not been customized to alter these values)
	10 to 99	These values are reserved for user-defined return values.
3	Bad return code from the IBM_Trombone_Custom_Server (assuming that the IBMTromboneCall state table has not been customized to alter these values)
	100	IBMTromboneOut state table returned a trombone_make_call_status outside the valid range (0 to 99).
	101	The IBMTromboneOut state table performed a CloseHostServerLink while the custom server was waiting for a response to the TromboneMakeCall request
	102	The custom server request is invalid at this time (probably because of an error in the sequence of custom server calls).
	103	CA_Open_CHP_Link() failed, probably because there are not enough free CHPs.
	104	CA_Execute_State_Table() failed, probably because of an invalid state table name, entry point, or the state table not being validated.
	105	CA_Get_Channel_Info() failed, probably because the outbound call was terminated.
	106	A TDM connect or disconnect request failed because of an adapter hardware problem.
	107	A TDM connect or disconnect request failed because the requested port was already connected. This may be caused by other applications running that can make TDM connect and disconnect requests.
	108	A TDM connect or disconnect request failed because there was no call present. One of the parties has probably hung up.
	109	A TDM connect or disconnect request failed because the Timeslot Manager is not ready. It may be very busy or not available.
	110	A TDM connect or disconnect request failed because of an internal custom server problem.
	111	A TDM connect or disconnect request failed because of an unexpected return code from the connect or disconnect request.
	112-199	Spare
4	Bad status returned from the IBMTromboneCall state table itself (assuming that the IBMTromboneCall state table has not been customized to alter these values)
	200	IBM_Trombone_Custom_Server returned a trombone_make_call_status outside the valid range (0 to 199).
	201	Could not open a server link to the IBM_Trombone_Custom_Server.
	202	Failed to send the data for the TromboneMakeCall request to the IBM_Trombone_Custom_Server
	203 to 207	Bad return code from the ReceiveData corresponding to the TromboneMakeCall request. A status of 203 to 207 represents a return edge of 1 to 5.
	208	The caller hung up during the trombone operation.
	209	Received a Fax Event during the trombone operation (SV227 is probably not set to zero).
	210	Received a Voice Event during the trombone operation (SV227 is probably not set to zero).
	211	Received a Long Silence Event during the trombone operation.
	212	Received a Line Problem Event during the trombone operation.
	213	Received a Timeout Event during the trombone operation.
	214	The timeout specified in the Wait Event was invalid.
	215	Failed to send the data for the TromboneDisconnectCall request to the IBM_Trombone_Custom_Server.
	216 to 220	Bad return code from the ReceiveData corresponding to the TromboneDisconnectCall request. A status of 216 to 220 represents a return edge of 1 to 5.
	221	Failed to send the data for the TromboneConnectCall request to the IBM_Trombone_Custom_Server.
	222 to 226	Bad return code from the ReceiveData corresponding to the TromboneConnectCall request. A status of 222 to 226 represents a return edge of 1 to 5.
	227	The ReceiveData corresponding to the TromboneConnectCall request timed out.
	228	The ReceiveData corresponding to the TromboneDisconnectCall request timed out.
	229	The ReceiveData corresponding to the TromboneCall or TromboneMakeCall request. timed out. If you are using the IBMTromboneRdy state table, you probably specified a fairly short time for the timeout. Call IBMTromboneRdy again until you are sure that the call has failed.
	230 to 249	Spare: may be used for user-defined values.
5	Bad status returned from the IBMTromboneCall state table itself, caused by a problem with music on hold. Most of these errors are generated in the IBMTromboneMus state table, which is invoked by the IBMTromboneCall state table (assuming that the IBMTromboneCall and IBMTromboneMus state tables have not been customized to alter these values)
	250	Music on hold was specified, but the IBMTromboneMus state table was either not available, or not validated. This might occur if the juke_box application is not installed.
	251	The IBMTromboneMus state table returned a status outside the valid range (> 251).
	252	Unrecognized on_or_off value supplied to the IBMTromboneMus state table.
	253	Could not open a server link to the juke_box custom server.
	254	Failed to send the data for the juke_box_start_music request to the juke_box custom server.
	255 to 259	Bad return code from the ReceiveData corresponding to the juke_box_start_music request. A status of 255 to 259 represents a return edge of 1 to 5.
	260	The status returned by the juke_box_start_music request was out of range (<1000).
	261	The requested music was not available.