IPCTerminate Function

Navigation: Scripting Reference Manual > Functions & Subroutines > IPCTerminate

IPCTerminate

Description

This function disconnects from all active nodes in a connections array and queues them for termination. A maximum wait parameter can be used to specify a maximum waiting period for all of the remote nodes to become idle before termination is initiated.

Syntax

count = IPCTerminate( connections(), options, maxwait )

Parameters

count (Long)

Returned number of remote nodes for which termination was initiated.

connections() As T_IPCINSTANCE

An array of T_IPCINSTANCE structures, with each structure defining the connection information for a remote node.

options As String

This space delimited string argument specifies optional parameters indicating how termination should proceed. Options are:

force

Forces a remote node to terminate even if it is busy. A busy remote node may not terminate or delete its working directory unless the force option is used. The force option should only be used when the standard, unforced call to IPCTerminate() fails to terminate the remote node(s). Use of this option can be very messy for the operating system and potentially result in memory and/or resource leaks.

clean OR sterilize

clean

Deletes the local working directory on the remote node upon termination if the directory is empty.

sterilize

Deletes the local working directory on the remote node upon termination even if the directory is not empty. When using the sterilize option, the output window report may contain the message, "GetOverlappedResult call failed with following error: The pipe has been ended.". This is expected due to the abrupt nature of the disconnect with this method.

maxwait As String

This argument indicates the maximum wait time for all remote nodes to become idle before initiating the termination. Time units may be indicated using the following conventions: s=seconds, m=minutes, h=hours, d=days, w=weeks, mo=months (ex. "10s" = 10 seconds). In the absence of a time unit designation, seconds will be assumed. If using the "force" option, maxwait should be empty.

Example

The example below demonstrates how to to load the connections() array with remote node connection information stored in a configuration file and then go through a series of connect, query and reconnect commands before finally terminating the remote FRED instances.

Sub Main

EnableTextPrinting(True)

ClearOutputWindow()

'Use a CSV file to populate the connections array

Dim nRemoteLoad As Long

Dim connections() As T_IPCINSTANCE

Dim configFile As String, configLocation As String

configLocation = GetDocDir() & "\"

configFile = "DCTestBed_Connections.csv"

nRemoteLoad = IPCLoadConfigFile( connections(), configLocation & configFile )

'Connect to the remotes

Dim nConnect As Long

nConnect = IPCConnect( connections() )

'Query the status of the connections

Dim nQuery As Long

nQuery = IPCQueryStatus( connections(), "detail" )

'Disconnect from the remote nodes and save a snapshot file of the connections array

Dim nDisconnect As Long

Dim snapShot As String

snapShot = configLocation & "DCTestBed_Reconnect.csv"

nDisconnect = IPCDisconnect( connections(), snapShot )

'Now reconnect

Dim nReconnect As Long

nReconnect = IPCReconnect( connections(), snapShot )

'Query the status again

nQuery = IPCQueryStatus( connections(), "detail" )

'Terminate the connections

Dim nTerminate As Long

nTerminate = IPCTerminate( connections(), "sterilize", "1d" )

End Sub

The IPC commands generally report information to the output window that may be used as diagnostics. For the example script shown above, the following output is reported:

[MASTER]IPCLoadConfigFile: 3 of 3 connections read from 'C:\temp\DCTestBed_Connections.csv'

index active speed host status

1 true 100 computer1 ---

2 true 100 computer2 ---

3 true 100 computer3 ---

[MASTER]IPCConnect: 3 of 3 Remote FRED instances connected and running

index host result message

1 computer1 connected ---

2 computer2 connected ---

3 computer3 connected ---

[MASTER]IPCQueryStatus: 3 connections queried

index host message

1 computer1 idle

2 computer2 idle

3 computer3 idle

index host handle cmd handle message

1 NI_00000012 HPOL check

PING

IDLE idle

2 NI_00000013 HPOL check

PING

IDLE idle

3 NI_00000014 HPOL check

PING

IDLE idle

[MASTER]IPCDisconnect: 3 of 3 Remote FRED instances disconnected but still running

[MASTER]IPCReconnect: 3 of 3 Remote FRED instances reconnected

index host message

1 computer1 reconnected - idle

2 computer2 reconnected - idle

3 computer31 reconnected - idle

[MASTER]IPCQueryStatus: 3 connections queried

index host message

1 computer1 idle

2 computer2 idle

3 computer3 idle

index host handle cmd handle message

1 NI_00000015 HPOL check

PING

IDLE idle

2 NI_00000016 HPOL check

PING

IDLE idle

3 NI_00000017 HPOL check

PING

IDLE idle

[MASTER]IPCTerminate: 3 of 3 Remote FRED instance terminations initiated

index host message

1 computer1 terminate - initiated

2 computer2 terminate - initiated

3 computer3 terminate - initiated