DH_ParsePointString

Cogent API and Utilities: Version 4.1
Prev |  | Next

# `DH_ParsePointString`

`DH_ParsePointString` -- parses the return of `DH_ReadPoint` and `DH_RegisterPoint`.

## Syntax

    #include <cogdb.h>

``ST_STATUS DH_ParsePointString`(PT_pCPOINT ppoint, char* name, char* msgdata, char** msgend, ER_hLIST elist);`

## Arguments

`ppoint`

  A pointer to a point structure which will be filled in by this function. The `name` element of the structure is not filled in, but is placed in the `name` argument instead.

  All other fields are valid, and will be treated by the write, but in the first call on a point the address field must be zero. It will be filled in automatically. This address will be valid so long as the point exists in the datahub, and if, in subsequent `DH_*` functions, the address is provided for this point, the function will run slightly faster.

`name`

  A pointer to a buffer which will be filled in with the point name by this function.

`msgdata`

  A pointer to a character string which contains one or more point specifications. This can be the buffer portion of an `IP_hMSG`, available using the IP_MsgBuffer function.

`msgend`

  Returns a pointer to a (char*) variable which will point to the character following the end of the point specification parsed by this call. This pointer may be passed back to a subsequent call to `DH_ParsePointString` to handle more than one point specification in a single incoming message, as may occur for a point exception.

`elist`

  A return value containing error information. This is unimplemented in this version, and should be `NULL`.

## Returns

`ST_OK` on success, `ST_ERROR` on failure, or some other value of `ST_STATUS`. `ST_ERROR` means the `msgdata` did not contain a valid point specification.

## Description

This function parses the return value from `DH_ReadPoint` and `DH_RegisterPoint`, or a message received through an asynchronous message (exception) from the datahub, and places the result in the provided point structure.

The name of the point is not modified in the point structure, as there is no clear manner in which the name should be handled. This leaves it up to the programmer to perform the memory allocation and deallocation of the point name storage as required. The `msgend` argument allows the programmer to deal with more than one point definition in a single message, which is typical of datahub exception messages. When the last point definition in the message has been parsed, then `msgend` will point to a zero length string `(**msgend == '\0')`.

## See Also

Communicating with the Cascade DataHub, DH_ParsePointMsg

Prev | Home | Next
`DH_ParsePointMsg` | Up | `DH_PointAdd`, `DH_PointDivide`, `DH_PointMultiply`

Copyright 1995-2002 by Cogent Real-Time Systems, Inc.