CNVCreateReader

int CNVCreateReader (const char *networkVariablePathname, CNVStatusCallback statusCallback, void *callbackData, int waitTime, intptr_t reserved, CNVReader *reader);

Purpose

Creates a reader connection to the network variable that you specify with the networkVariablePathName parameter. You can read new values of the network variable by calling CNVRead.

Note Note  The throughput rate of data with reader and asynchronous reader connections is slower than with subscriber and buffered subscriber connections. If throughput rate is critical to your application, consider using subscriber or buffered subscriber connections instead.
Note Note  To avoid deadlocks, do not call this function in a network variable callback function.

Parameters

Input
Name Type Description
networkVariablePathname const char * Pathname of the network variable to connect. The format of the pathname is \\machineName\processName\folderNames\variableName, which is similar to the format of items on network shares and is not case-sensitive. The following list shows examples of pathnames:

  • \\localhost\my_process\my_folder1\my_folder2\my_variable
  • \\test_machine\my_process\my_sub_process\my_variable
  • \\192.168.1.100\my_process\my_variable
  • \\test_machine.my_network.com\my_process\my_variable
  • \\localhost\System\DAQmx\Server Polling Rate
  • \\localhost\system\my_variable

You can explicitly create and configure your variables using the NI Distributed System Manager that ships with LabWindows/CVI or using the Configuration Functions in the Network Variable Library. You also can use previously created explicit variables.

If you specify a new variable name in the system process, as shown in the last example, then the Network Variable Library creates a variable implicitly. Implicit variables can hold values of any type, always have the single-writer restriction, and do not support server-side buffering. The Network Variable Library automatically deletes an implicit variable when all of its clients disconnect, that is, when there are no outstanding connections to it.

Carefully decide whether to use implicit or explicit variables depending on your application and deployment needs.

Note Note  National Instruments recommends that you use only alphanumeric characters in process, folder, and variable names. If the name contains single quotation mark ('), backslash (\), period (.), newline (\n), or carriage return (\r) characters, you must escape these characters by enclosing the name in single quotation marks. If the contains single quotation mark characters, you also must precede that character with another single quotation mark.

For example, to specify \\localhost\process'Name\variable.Name as a URL, enter the following:

  • 'process''Name' as the process name
  • 'variable.Name' as the variable name

The resulting URL is \\localhost\\'process''Name'\'variable.Name'.

This rule does not apply to computer names.
statusCallback CNVStatusCallback The function that the library calls when the connection status of a successfully created network variable changes. Connection status events occur when there is a significant network delay and NI-PSP attempts to reconnect. The library calls this function asynchronously in a worker thread. You can pass NULL if you do not want this notification.

The function you pass in this parameter must have the following prototype:

void CVICALLBACK Callback (void * handle, CNVConnectionStatus status, int error, void * callbackData);


Upon entry to the callback, the handle parameter contains the handle of the connection that is generating the event. The status parameter contains the status of the connection. The error parameter indicates any errors in the connection. The callbackData parameter of the callback contains the value you provide in the callbackData parameter of this function.

Note  Return from this function as soon as possible to avoid blocking other network variable events and operations. If needed, you can use PostDeferredCallToThread to process this event on a different thread. From within this callback function, you must also avoid calling the Network Variable Library to create or dispose connections and browsers, get or put buffered data, read or write data, get or set connection attributes, and browse for variables to prevent deadlocks.
callbackData void * The callback data that the library passes to the associated callback functions.
waitTime int Number of milliseconds the library waits for this operation to complete. Pass CNVWaitForever to wait indefinitely.
reserved intptr_t You must pass zero. This parameter is reserved for future use.
Output
Name Type Description
reader CNVReader Returns a handle that you can use to identify the network variable connection in subsequent function calls. Call CNVDispose to dispose the handle when you are done using it.

Return Value

Name Type Description
status int Return value indicating whether the function was successful. One indicates that a next item was found, zero indicates that a next item was not found, and a negative number indicates that an error occurred.

You can call CNVGetErrorDescription to obtain a string that describes the error.

Additional Information

Library: Network Variable Library

Include file: cvinetv.h

LabWindows/CVI compatibility: LabWindows/CVI 8.1 and later

WAS THIS ARTICLE HELPFUL?

Not Helpful