# isdnStartProtocol

Starts up an ISDN protocol stack instance on a specified context.

#### Prototype

DWORD isdnStartProtocol ( CTAHD ctahd, unsigned protocol, unsigned netoperator, unsigned country, unsigned partner_equip, unsigned nai, void *parms)

Argument | Description
ctahd | Context handle associated with a D channel returned by ctaCreateContext.
protocol | Stack mode to start protocol instance in: ISDN_PROTOCOL_Q931CC for ACU stack mode. ISDN_PROTOCOL_LAPD for LAPD stack mode. ISDN_PROTOCOL_CHANNELIZED for channelized stack mode.
netoperator | Network operator variant to start. Refer to Valid netoperator and country combinations.
country | Country mode in which the network operator variant starts. A variant's behavior can change depending on the country specified. Refer to Valid netoperator and country combinations. country must be the same for all NAIs on a single board.
partner_equip | Type of equipment connected to the board. Refer to partner_equip settings.
nai | Network access identifier (NAI) of the D channel to link to the protocol stack instance.
parms | Pointer to the parameter block/structure required by the protocol: For access to the parameters for NMS ISDN in LAPD stack mode, use the ISDN_PROTOCOL_PARMS_LAPD structure, as described in ISDN_PROTOCOL_PARMS_LAPD structure. For access to the parameters for NMS ISDN in ACU stack mode, use ISDN_PROTOCOL_PARMS_Q931CC, as described in ISDN_PROTOCOL_PARMS_Q931CC structure. For access to the parameters for NMS ISDN in Channelized stack mode, use the ISDN_PROTOCOL_PARMS_CHANNELIZED structure, as described in ISDN_PROTOCOL_PARMS_CHANNELIZED structure. When parms is NULL, the default parameters for the protocol are used. The default parameters for each protocol enable the required service access points (SAPIs). For the ACU stack mode, all the services are supported by default. The size field of the structure must contain the size of the structure. Refer to Overview of API data structures for details on the contents of these parameter structures.

### Valid netoperator and country combinations

The following table lists the valid netoperator and country combinations:

netoperator value | Country value | Country
ISDN_OPERATOR_ATT_4ESS ISDN_OPERATOR_ATT_5E10 ISDN_OPERATOR_NT_DMS ISDN_OPERATOR_NT_DMS250 ISDN_OPERATOR_NI2 | COUNTRY_USA | USA
ISDN_OPERATOR_FT_VN6 | COUNTRY_FRA | France
ISDN_OPERATOR_AUSTEL_1 | COUNTRY_AUS | Australia
ISDN_OPERATOR_ETSI | COUNTRY_AUS, COUNTRY_BEL, COUNTRY_GER, COUNTRY_SWE, COUNTRY_SGP, COUNTRY_GBR, COUNTRY_CHINA, COUNTRY_EUR | Australia, Belgium, Germany, Sweden, Singapore, Great Britain, and China. COUNTRY_EUR includes the following countries: Austria, Belgium, Denmark, Finland, Germany, Greece, Iceland, Ireland, Italy, Liechtenstein, Luxembourg, Netherlands, Norway, Portugal, Russia, Spain, Sweden, Switzerland, and the UK.
ISDN_OPERATOR_HONG_KONG | COUNTRY_HONG_KONG | Hong Kong
ISDN_OPERATOR_KOREA | COUNTRY_KOR | Korea
ISDN_OPERATOR_NTT | COUNTRY_JPN | Japan
ISDN_OPERATOR_TAIWAN | COUNTRY_TWN | Taiwan
ISDN_OPERATOR_ECMA_QSIG | NA | country is ignored if variant is QSIG.
ISDN_OPERATOR_DPNSS | COUNTRY_EUR | Europe

The following table shows the ISDN and DPNSS run module files for NMS boards:

Board | ISDN | DPNSS
AG (except for AG 2000-BRI boards) | isdngen.leo | dpnss.leo
CG 6565/C | c6565igen.dlm | c6565dpnss.dlm
CG 6060/C | c6060igen.dlm | c6060dpnss.dlm

For AG 2000-BRI boards, the following table shows the valid netoperator values and the corresponding run module file:

netoperator value | Variant | Run module file
ISDN_OPERATOR_ETSI | ETSI | brietsi.leo
ISDN_OPERATOR_NTT | NTT | brintt.leo
ISDN_OPERATOR_VN6 | VN6 | brivn6.leo

### partner_equip settings

Refer to the following table when setting the partner_equip argument:

If board is... | And NMS ISDN is to run in... | Set partner_equip to:
--- | --- | ---
Connected to network | ACU stack mode | EQUIPMENT_NT
Connected to network | LAPD stack mode | EQUIPMENT_DCE
Acting as a network | ACU stack mode | EQUIPMENT_TE
Acting as a network | LAPD stack mode | EQUIPMENT_DTE

NMS ISDN also supports DPNSS. For DPNSS, the designations TE and NT do not apply. For the DPNSS implementation, TE maps to PBX A and NT maps to PBX B. To run PBX A, the partner equipment designation is EQUIPMENT_NT.

By default, PBX A is assigned to side X and PBX B is assigned to side Y. Use the NS behavior bits to modify this setting.

#### Return values

Return value | Description
SUCCESS |
CTAERR_BAD_ARGUMENT | protocol argument is invalid, or the size field of the parms data structure does not match the size of the structure corresponding to the protocol value.
CTAERR_INVALID_CTAHD | Context handle is invalid.
CTAERR_INVALID_STATE | One of the following conditions exists: The context is not open. An ISDN protocol stack instance is being started on the same context by a previous call. An instance is already started on the context. An instance on the context is in the process of stopping.
CTAERR_OUT_OF_MEMORY | Memory allocation failed on the host machine.
ISDNERR_CHANNELIZED_ON_MULTIPLE_BOARDS | An NFAS group is defined including multiple boards, and an attempt was made to start the stack in channelized stack mode.
ISDNERR_PROTOCOL_NS_FAILURE | NFAS groups are configured, and an attempt was made to start the stack using a variant that does not support NFAS.
ISDNERR_RACE_STARTING_PROTOCOL | An attempt was made to restart the stack directly after stopping it, before it was completely stopped. The process of stopping the stack can take several seconds.

#### Events

Event name | Description
ISDNEVN_START_PROTOCOL | Value field of the received event contains the completion status of the protocol starting operation, as follows: SUCCESS ISDNERR_BAD_NAI Network access identifier (NAI) in the protocol parameters structure is not valid. Or, if duplicate NAI values are configured, the NAI and NFAS group couple is not valid. ISDNERR_INCOMPATIBLE_LIB NMS ISDN library used is incompatible with the run module. ISDNERR_INVALID_COUNTRY Country specified is invalid for the network operator specified. ISDNERR_INVALID_OPERATOR Network operator specified is not supported by the run module. ISDNERR_INVALID_PARTNER partner_equip is not supported by the run module. ISDNERR_INVALID_PROTOCOL protocol argument is not supported by the run module. ISDNERR_NAI_IN_USE Another thread or process has already started a protocol for the same network access identifier. ISDNERR_PROTOCOL_CC_FAILURE Call control parameters are invalid. ISDNERR_PROTOCOL_DL_FAILURE Data link parameters are invalid. ISDNERR_PROTOCOL_NS_FAILURE Network signaling parameters are invalid. ISDNERR_PROTOCOL_PH_FAILURE Physical layer parameters are invalid.

#### Details

This function starts the specified protocol on the board that is associated with the specified ctahd.

The run module is specified in the board keyword file. For information, refer to the NMS ISDN Installation Manual and the NMS OAM System User's Manual.

If the parms pointer is NULL, the default values for the specified protocol are used. It is assumed that an HDLC data stream was connected to the specified HDLC controller during initialization or by explicit switching calls. The parameters for the particular selected protocol are found in the parms data structure defined in isdnparm.h.

#### See also

isdnStopProtocol

#### Example 1

DWORD mystartisdn (CTAHD ctahd) /* Use defaults */
{
CTA_EVENT event;
DWORD ret;
char errortext[40];
unsigned nai = 0;
nai = 0;
ret = isdnStartProtocol( ctahd, ISDN_PROTOCOL_Q931CC,
ISDN_OPERATOR_NI2, COUNTRY_USA, ISDN_PARTNER_NT, nai, NULL);
if( ret != SUCCESS)
{
ctaGetText(ctahd, ret, errortext, 40);
printf("START_FAIL: %s\n", errortext );
return MY_ERROR_START_FAILED;
}
myWaitForEvent( ctahd, &event);
if( event.value != SUCCESS)
{
ctaGetText(ctahd, event.value, errortext, 40);
printf("START_FAIL: %s\n", errortext) );
return MY_ERROR_START_FAILED;
}
return SUCCESS ;
}

#### Example 2

DWORD mystartisdn (CTAHD ctahd) /* User-specified parms */
{
CTA_EVENT event;
DWORD ret;
char errortext[40];
unsigned nai;
unsigned j;
ISDN_PROTOCOL_PARMS_Q931CC parms;
memset( parms, 0, sizeof parms);
parms.size = sizeof(ISDN_PROTOCOL_PARMS_Q931CC);
nai = 0;
j = 0;
parms.nfas_group = 0;
parms.services_list[j++] = ACU_FAX_SERVICE;
parms.services_list[j++] = ACU_VOICE_SERIVCE;
parms.services.list[j] = ACU_NO_SERVICE;
/*
** NOTE: The last service MUST contain ACU_NO_SERVICE
*/
ret = isdnStartProtocol( ctahd, ISDN_PROTOCOL_Q931CC,
ISDN_OPERATOR_NI2, COUNTRY_USA, ISDN_PARTNER_NT, nai, &parms);
if( ret != SUCCESS)
{
ctaGetText(ctahd, ret, errortext, 40);
printf("START_FAIL: %s\n", errortext );
return MY_ERROR_START_FAILED;
}
myWaitForEvent( ctahd, &event)
if( event.value != SUCCESS)
{
ctaGetText(ctahd, event.value, errortext, 40);
printf("START_FAIL: %s\n", errortext );
return MY_ERROR_START_FAILED;
}
return SUCCESS;
}