TipcSrvCreate

Name

TipcSrvCreate — create the connection to RTserver

Synopsis

T_BOOL TipcSrvCreate(create_status) 
T_IPC_SRV_CONN_STATUS create_status; 

Arguments

create_status — whether to create a warm connection (use T_IPC_SRV_CONN_WARM) or a full connection (use T_IPC_SRV_CONN_FULL)

Return Values

TRUE if the connection to RTserver was successfully created, FALSE otherwise.

Diagnostics

If TipcSrvCreate fails, it returns NULL and sets the global SmartSockets error number to one of:

Description

TipcSrvCreate creates the connection to RTserver. The RTclient becomes part of the project named in the option Project, can subscribe to subjects, can publish (send) messages to RTserver, and receive messages from RTserver. Each project is self-contained; messages cannot be sent between projects. When the connection to RTserver is created, the RTclient immediately starts subscribing to the subject named in the option Unique_Subject. The RTclient can call TipcSrvSubjectSetSubscribe to start subscribing to other subjects.

TipcSrvCreate uses several RTclient options to control the creation of the connection to RTserver:

In addition to these options, the boolean option Server_Auto_Connect is related to TipcSrvCreate. An RTclient can have a warm connection to RTserver, which is a subset of a full connection to RTserver. Most of the other TipcSrv functions, such as TipcSrvMsgSend, call TipcSrvCreate if Server_Auto_Connect is set to TRUE and the RTclient does not have a full connection to RTserver. See TipcSrvDestroy for more information on warm connections to RTserver.

Logical Connection Names in Server_Names

The most important option is Server_Names, which is used to find and start RTserver. Server_Names is a list of logical connection names. Each logical connection name has the form protocol:node:address, which can be shortened to protocol:node, protocol, or node, and is specified this way:

Using a Start Prefix

Each logical connection name can also have a start prefix at the front, which must be separated from the name with a colon:

start_prefix:protocol:node:address 

The value for start_prefix controls whether and when the RTclient tries to start RTserver:

Traversing Server_Names

A client traverses the list of names in Server_Names at most Server_Start_Max_Tries. Between each traversal the client sleeps for Server_Start_Delay seconds. Each time an RTclient tries to start RTserver, it waits for up to Server_Start_Timeout seconds for that RTserver to finish initializing. For each entry in Server_Names, a client tries to connect, then possibly try to start RTserver (depending on what start prefix is used), then try to connect again.

This example shows the algorithm used by TipcSrvCreate:

randomize Server_Names list if _random is used 
 
for (each $try from 1 to Server_Start_Max_Tries) { 
 
  for (each $name in Server_Names) { 
    connect to RTserver using $name 
    if (connection could be created) { 
      if (no connection previously existed) { 
        resend old GMD messages 
      } 
      execute server create callbacks 
      return 
    } 
    else { 
      if ($name has the start prefix "start_always" 
          or $name has no start prefix 
          or ($name has the start prefix "start_on_demand" 
              and $try > 1)) { 
        start RTserver with command "rtserver -node node" 
        wait up to Server_Start_Timeout seconds for RTserver to init 
        connect to RTserver using $name 
        if (connection could be created) { 
          if (no connection previously existed) { 
            resend old GMD messages 
          } 
          execute server create callbacks 
          return 
        } 
      } /* if we should try to start RTserver */ 
    } /* if no connection */ 
  } /* for each name */ 
 
  sleep for Server_Start_Delay seconds 
} /* for each try */ 

The start_on_demand start prefix only starts RTserver if the option Server_Start_Max_Tries is set to a value larger than 1 (the default).

RTclient Options

The RTclient options (Project, Server_Names, and so on) are only accessed when the RTclient creates a connection to RTserver (see below for special handling for Project, Unique_Subject, and Default_Subject_Prefix). If one of these options is changed, it has no effect until the next time the RTclient creates a connection to RTserver. One possible way of doing this is to destroy the connection to RTserver (but keep it warm) and then create a new connection to RTserver using the warm information. This code can be used to change an option like Project and have it take effect immediately:

/* destroy existing connection to RTserver, but keep it warm */ 
if (!TipcSrvDestroy(T_IPC_SRV_CONN_WARM)) { 
  return;  /* error */ 
} 
 
/* change Project */ 
TutCommandParseStr("setopt project new_project"); 
 
/* create a new connection to RTserver from warm info */ 
if (!TipcSrvCreate(T_IPC_SRV_CONN_FULL)) { 
  return;  /* error */ 
} 

The Project option is set as read-only while RTclient has a full connection to RTserver. This prevents confusion in case this option is changed after the full connection is created.

Because the Unique_Subject and Default_Subject_Prefix options may be used each time RTclient publishes a message, these options are set as read-only while RTclient has a warm or full connection to RTserver. This prevents misconfiguration during normal publish-subscribe operation. For a change in Unique_Subject or Default_Subject_Prefix to take effect, the connection to RTserver must be fully destroyed. (No warm connection can be left.)

GMD Handling

If the RTclient had no connection at all to RTserver, the TipcSrvCreate calls TipcSrvGmdResend to resend any old messages for GMD. This is needed to preserve message sequence number order, even for a warm connection. TipcSrvCreate does not create any directories for GMD if no resending is needed. This prevents large numbers of unused directories from being created for large projects.

Creating a Full Connection

If a full connection to RTserver is created, some one-time handshaking between RTclient and RTserver takes place. RTclient sends a CONNECT_CALL message to RTserver and RTserver responds with a CONNECT_RESULT message.

Callbacks

TipcSrvCreate also creates many callbacks, several of which can be destroyed by the user if the user wants to replace the default functionality:

Caution

An RTclient cannot have a connection to more than one RTserver at a time unless using the TipcSrvConn API functions that handle multiple connections.

See Also

TipcSrvDestroy, TipcSrvGetConnStatus

Examples

This example sets the options Project and Server_Names, then connects to RTserver:

TutCommandParseStr("setopt project demo"); 
TutCommandParseStr("setopt server_names tcp:moe"); 
 
if (!TipcSrvCreate(T_IPC_SRV_CONN_FULL)) { 
  return;  /* error */ 
}