HP Operations Manager for Windows

opcif_open()


   #include opcapi.h

   int opcif_open(
                  int          interface_type,     /* in */
                  const char   *instance,          /* in */
                  int          mode,               /* in */
                  int          max_entries,        /* in */
                  int          *interface_id       /* out */
                 );

Parameters

interface_type
Specifies the type of interface to use from:

Agent Message Stream Interface

Used by external message processors (for example, event correlation engines):

  • OPCAGTIF_EXTMSGPROC_READ
  • OPCAGTIF_EXTMSGPROC_READWRITE
  • OPCAGTIF_EXTMSGPROC_WRITE
instance
Name of the interface instance which is registered for one of the interface types above. The name is limited to a length of 12 alpha-numeric characters because it is also part of the queue file name.

mode
To specify whether the interface is opened if the HPOM processes are not running. Use either:
  • OPCIF_ALWAYS (default)
  • OPCIF_AGT_RUNNING

The following options specify whether the opcif_read() API will wait for available data or not; in the WAIT case, the calling process will be blocked until data is available or the process receives an interrupt:

  • OPCIF_READ_WAIT (default)
  • OPCIF_READ_NOWAIT

To specify the handling of unread messages if the connected process closes the interface or aborts, use one of the following options:

  • OPCIF_CLOSE_FORWARD (default)
  • OPCIF_CLOSE_DISCARD

In the first case, messages in the read-queue are appended to the write-queue; in the second, these messages are discarded when the external program closes the interface.

It is possible to combine these options using the '|' operator.

max_entries
Specifies the maximum number of entries in the read-queues. If this number is exceeded, HPOM stops writing to the queue. When the reading process has emptied the queue, it is notified by an error value returned by opcif_read(). The application must then disconnect and reopen the interface. To disable this check, specify 0 for max_entries.

interface_id
The returned value must be used in subsequent calls to the APIs to refer to this instance of the interface.

Description

Use the function opcif_open() to connect to an instance of one of the following interfaces:

Return Values

OPC_ERR_OK:
interface correctly opened

OPC_ERR_INVALID_OUTPARAM:
pointer to interface_id is invalid

OPC_ERR_ACCESS_DENIED:
access denied

OPC_ERR_INVALID_INTERFACE_INSTANCE:
instance name contains invalid characters, or is too long

OPC_ERR_INVALID_INTERFACE_TYPE:
no such interface type

OPC_ERR_CANT_INIT:
initialization of queues failed

OPC_ERR_CANT_OPEN_READQUEUE:
unable to open readqueue

OPC_ERR_CANT_OPEN_WRITEQUEUE:
unable to open writequeue

OPC_ERR_CANT_INFORM_MSGA:
informing message agent failed

OPC_ERR_NO_MEMORY:
memory allocation failed

Versions

HPOM for Windows A.07.50 and later

See Also

HPOM Interfaces