gclib  322
Communications API for Galil controllers and PLCs
 All Data Structures Files Functions Variables Typedefs Macros Pages
GCLIB_DLL_EXPORTED GReturn GCALL GUtility ( GCon  g,
GOption  request,
GMemory  memory1,
GMemory  memory2 
)

Provides read/write access to driver settings and convenience features based on the request variable.

Note
The open source library, gclibo.h, has wrappers for most of these utilities.
Parameters
gConnection's handle.
requestDefines the request. Input/Output and type of memory are implicit in the value of request. The following lists the supported request values.
  • G_UTIL_TIMEOUT Read initial timeout value, as specified in GOpen() via --timeout switch.
    • memory1 is output and must be a pointer to an unsigned short.
    • memory2 is ignored, use null.
  • G_UTIL_TIMEOUT_OVERRIDE See GTimeout(). Write/Read override timeout value.
    • memory1 is input. If nonnull, value must be a pointer to a short which overrides the timeout. Write G_USE_INITIAL_TIMEOUT to use initial timeout. If null, no write occurs.
    • memory2 is output. If nonnul, value must be a pointer to a short which will be filled with the current override. G_USE_INITIAL_TIMEOUT indicates initial timeout used. If null, no read occurs. memory2 is processed before 'memory1`.
  • G_UTIL_VERSION See GVersion(). Returns the library version. A valid connection (g) is not necessary, e.g. g may be null.
    • memory1 is output, and must be a GCStringOut. Data will be null terminated, even if the data must be truncated to do so.
    • memory2 is input and must be a pointer to a GSize holding the length of the buffer in memory1.
  • G_UTIL_INFO See GInfo(). Returns information about the connection.
    • memory1 is output and must be a GCStringOut. Data will be null terminated, even if the data must be truncated to do so.
    • memory2 is input and must be a pointer to a GSize holding the length of the buffer in memory1.
  • G_UTIL_SLEEP See GSleep(). Platform-independent sleep. A valid connection (g) is not necessary, i.e. g may be null.
    • memory1 is input and must be a pointer to an unsigned int, units are milliseconds.
    • memory2 is ignored, use null.
  • G_UTIL_ADDRESSES Provides a \n delimited listing of all available IP addresses, PCI addresses, and COM ports. A valid connection (g) is not necessary, i.e. g may be null.
    • memory1 is output and must be a GCStringOut. Data will be null terminated, even if the data must be truncated to do so.
    • memory2 is input and must be a pointer to a GSize holding the length of the buffer in memory1.
  • G_UTIL_IPREQUEST Listens and returns a \n delimited listing of Galil MAC addresses sending BOOT-P or DHCP requests. The function will listen, and block, for roughly 5 seconds. A valid connection (g) is not necessary, i.e. g may be null.
    • memory1 is output and must be a GCStringOut. Data will be null terminated, even if the data must be truncated to do so.
    • memory2 is input and must be a pointer to a GSize holding the length of the buffer in memory1.
  • G_UTIL_ASSIGN Provides a method to assign an IP address given a Galil MAC address and optionally a host NIC IP address. A valid connection (g) is not necessary, i.e. g may be null. The address to assign will be pinged to ensure its availability before the assign packet is sent. G_GCLIB_UTILITY_IP_TAKEN will be returned by GUtility() if the ping returns a response.
    • memory1 is input and must be a pointer to a GCStringIn containing the address that is to be assigned. e.g. "192.168.0.43"
    • memory2 is input and must be a pointer to a GCStringIn containing a comma-separated list with the controller's MAC address, followed by the IP address of the host's network interface to dispatch the assign packet. e.g. "00:50:4C:20:01:23, 192.168.0.42"
      If the host IP is omitted, the assign packet is sent out on all network interfaces. e.g. "00:50:4C:20:01:23"
  • G_UTIL_GCAPS_KEEPALIVE Provides method for kicking the gcaps server. After a default period of 10 minutes of inactivity, gcaps will disconnect the gclib client. To prevent a disconnect, communicate with the hardware or call G_UTIL_GCAPS_KEEPALIVE within the timeout period to reset the timer. The current interval can be optionally read and overwritten.
    • memory1 is output. If nonnull, value must be a pointer to a GSIZE which will be filled with the current gcaps timeout, in ms.
    • memory2 is input. If nonnull, value must be a pointer to a GSIZE which overrides the current gcaps timeout, in ms, for this connection.
  • G_UTIL_DEVICE_INITIALIZE Provides a method to reinitialize a connection after a reset, e.g. an RS command. Depending on the device type, the appropriate commands will be sent to configure the communication bus for optimal performance.
    • memory1 is ignored, use null.
    • memory2 is ignored, use null.
memory1An untyped pointer to data type required for request.
memory2An untyped pointer to data type required for request.
Returns
The success status or error code of the function. See gclib_errors.h for possible values.

See source of gclibo.c for examples of G_UTIL_TIMEOUT, G_UTIL_TIMEOUT_OVERRIDE, G_UTIL_VERSION, G_UTIL_INFO, G_UTIL_SLEEP.

Except for serial ports, each line from G_UTIL_ADDRESSES will be of the form address, revision report (^R^V).

1 10.1.3.168, DMC30010 Rev 1.2d
2 GALILPCI1, DMC1826 Rev 1.1a
3 COM7
4 COM8

See GAddresses() for an example of G_UTIL_ADDRESSES.

Note
Linux/OS X users must be root to use G_UTIL_IPREQUEST and have UDP access to bind and listen on port 67.

Each line from G_UTIL_IPREQUEST will be of the form model, serial_number, mac.

1 DMC4000, 291, 00:50:4c:20:01:23
2 DMC30000, 4184, 00:50:4c:40:10:58
//example for getting controllers requesting IPs
char buf[1024];
GSize len = sizeof(buf);
GUtility(0, G_UTIL_IPREQUEST, buf, &len);
cout << buf << "\n";
Note
Linux users must be root to use G_UTIL_ASSIGN and have UDP access to send on port 68.
//example of assigning an IP address.
GUtility(0, G_UTIL_ASSIGN, "10.1.3.178", "00:50:4c:40:10:58"); //Assign 10.1.3.178 TO 00:50:4c:40:10:58

Referenced by GAddresses(), GAssign(), GInfo(), GIpRequests(), GSleep(), GTimeout(), and GVersion().