Return to Technical Product Information        CCT Home

Main API Page   File List   Globals  

Libapi

CCTK User API Reference. More...

Functions

char* api_strerror (int api_errnum)
 Get application error message string.

void api_perror (const char *s)
 Print application error messages.

void ApiTermHandler (int signo)
 Default termination handler for libapi.

int BuildAndSendLinkedDataPacket (const char *fd, void *raw_value, const char *channel)
 Build and ship a linked data packet for a FD.

char* GetCmdMeas (const char *fd, int cmd_meas_num, char *cmd_meas_fd)
 Extract a command's measurement parameter FD from the system during run-time.

int GetDesType (const char *fd)
 Get the type of a specified descriptor.

int GetMeasData (const char *fd, meas_data_t *data)
 Get a measurement's FD characteristics.

int GetMeasType (const char *fd)
 Get the type of a specified measurement descriptor.

char* GetMeasUnit (const char *fd, char *unit)
 Extract a measurement's engineering unit from the system during run-time.

int GetMeasValue (const char *fd, int format_type, void *value, int *status)
 Get a measurement's current value and status from the system during run-time.

int GetNumCmdMeas (const char *fd)
 Get the number of parameters associated with a command from the system during run-time.

char* GetProjectName (char *name)
 Get the current project's ASCII name.

int IssueCmd (const char *fd, void *command_response_data,...)
 Issue a parameterized command.

int IssueValue (const char *fd, int format_type, void *value, void *command_response_data)
 Issue a command with value.

int SetMeasValue (const char *fd, int format_type, void *value)
 Set a measurement's processed or raw value during run-time.

int SysInit (const char *prog_name, void(*fp)())
 User process initialization.

void SysQuit (void)
 Clean up all system internals for the application. SysQuit() is an internal function used to detach the process from all system services.


Variables

int g_api_errno = 0
 Error number of the last application error message.

Detailed Description

CCTK User API Reference.

The C language User Application Programming Interface (API) for the Command and Control Toolkit (CCTK).

Function Documentation

void ApiTermHandler ( int signo )
 

Default termination handler for libapi.

ApiTermHandler is the default termination handler for any process calling SysInit() with a NULL argument for the termination handler. It will call SysQuit() to clean up the system and then exit with the standard exit() command. As is standard with shells, the exit code will be the signal received plus 128.

Returns:
none.

See also:
SysInit() SysQuit() exit()

int BuildAndSendLinkedDataPacket ( const char * fd,
void * raw_value,
const char * channel )
 

Build and ship a linked data packet for a FD.

Parameters:
fd   Descriptor name.
raw_value   Descriptor's raw value.
channel   Channel name.

BuildAndSendLinkedDataPacket() will build a linked data packet suitable to send to DataProc for the specified fd. It will then send the data packet out the specified channel. See BuildLinkedDataPacket() for information on the format of raw_value.

Note:
This is not an "efficient" method of sending data as the channel is opened and closed with each successive call. If speed is critical or large amounts of data need to be sent, manage the channel manually and use the BuildLinkedDataPacket() function to build the packets that will be sent.

Returns:
On successful completion SUCCESS is returned. Otherwise, if an error is encountered then FAILURE is returned and g_api_errno is set to indicate the error.
Example:
#include <stdio.h>
#include <stdlib.h>
#include "Channel.h"
#include "ApiTypes.h"

int main(int argc, char **argv)
{
  double value;
  char *channel_name = NEXT_AVAIL_CHAN;
  int rtn;

  SysInit(argv[0], NULL);

  value = 123.456;

  rtn = BuildAndSendLinkedDataPacket("FDNAME", &value, channel_name);

  if (rtn != SUCCESS) {
    printf("Error calling BuildAndSendLinkedDataPacket(), g_api_errno = %s\n", api_strerror(g_api_errno));
  }

  SysQuit();

  return EXIT_SUCCESS;
}

See also:
BuildLinkedDataPacket()

char * GetCmdMeas ( const char * fd,
int cmd_meas_num,
char * cmd_meas_fd )
 

Extract a command's measurement parameter FD from the system during run-time.

Parameters:
fd   Command descriptor name.
cmd_meas_num   Value from 0 ... n indicating which command parameter you want.
cmd_meas_fd   Data store which the measurement parameter's fd name will be stored.

GetCmdMeas() is a user API call which retrieves a command's measurement parameter from the real-time tables for a given command FD and measurement parameter number. This function returns the measurement FD in the form of a string.

Note:
Use GetNumCmdMeas() to determine the total number of parameters associated with a command.

Returns:
On successful completion a pointer to the measurement parameter's FD name is returned. Otherwise, if an error is encountered then NULL is returned and g_api_errno is set to indicate the error.
Example:
#include <stdio.h>
#include <stdlib.h>
#include "ApiTypes.h"

int main(int argc, char **argv)
{
  int i;
  char command_fd[MAX_FD_SIZE], param_fd[MAX_FD_SIZE];

  SysInit(argv[0], NULL);

  i = 0;
  strcpy(command_fd, "COMMAND FDNAME");

  if (GetCmdMeas(command_fd, i, param_fd) != NULL) {
    printf("Command %s parameter fd #%d = %s\n", command_fd, i, param_fd);
  }
  else {
    printf("GetCmdMeas() call failed!\n");
  }

  SysQuit();

  return EXIT_SUCCESS;
}

See also:
GetNumCmdMeas()

int GetDesType ( const char * fd )
 

Get the type of a specified descriptor.

Parameters:
fd   Measurement descriptor name.

GetDesType() is a user API call that returns the descriptor's type from the real-time tables for a specified fd.

The value is returned can be equated to one of the following defines declared in KTables.h: 

Measurement Descriptors:
        ANALOG_MEAS_DES_TYPE
        BYTEARRAY_MEAS_DES_TYPE
        DISCRETE_MEAS_DES_TYPE
        SIGNED_INT_MEAS_DES_TYPE
        UNSIGNED_INT_MEAS_DES_TYPE

Exception Descriptors:
        ANA_EXCPT_DES_TYPE
        BA_EXCPT_DES_TYPE
        DIS_EXCPT_DES_TYPE
        SIGNED_INT_EXCPT_DES_TYPE
        UNSIGNED_INT_EXCPT_DES_TYPE

Conversion Descriptors:
        POLY_CONV_DES_TYPE
        PIECEWISE_CONV_DES_TYPE
        SEG_LIST_INFO_TYPE
        STATE_CONV_DES_TYPE

Linker Descriptors:
        LDT1553_DES_TYPE
        LDT_AIC_DES_TYPE

Commanding Descriptors:
        EI_CMD_DES_TYPE (*NOTE: This is a derived type id)
        CMD_DES_TYPE_S
        SYS_CMD_DES_TYPE

Bus Descriptors:
        BUS_GENERIC_DES_TYPE
        BUS1553_DES_TYPE
        BUS_AIC_DES_TYPE

Port Descriptors:
        PORT_GENERIC_DES_TYPE
        PORT1553_DES_TYPE
        PORT_AIC_DES_TYPE
        PORT_ARS_DES_TYPE

Polling Descriptors:
        POLL1553_DES_TYPE

Notice Descriptors:
        NOTICE_DES_TYPE

Update Descriptors:
        UPDATE_DES_TYPE

In addition, the following macros have been defined in KTables.h:

        IS_MEASUREMENT_DES(des_type)
        IS_EXCEPTION_DES(des_type)
        IS_CONVERSION_DES(des_type)
        IS_LINK_DES(des_type)
        IS_COMMAND_DES(des_type) (*NOTE: This is a derived macro definition)
        IS_SYSTEM_COMMAND_DES(des_type)
        IS_BUS_DES(des_type)
        IS_PORT_DES(des_type)
        IS_POLL_DES(des_type)
        IS_NOTICE_DES(des_type)
        IS_UPDATE_DES(des_type)

        Each macro evaluates to true or false (1 or 0)

Returns:
GetDesType() returns the descriptor type, or if an error is encountered then FAILURE is returned and g_api_errno is set to indicate the error.
Example:
#include <stdio.h>
#include <stdlib.h>
#include "KTables.h"
#include "ApiTypes.h"

main(int argc, char **argv)
{
  int des_type;

  SysInit(argv[0], NULL);

  des_type = GetDesType("ANALOG_FDNAME");
  if (des_type == FAILURE) {
    printf("Invalid descriptor name specified!\n");
  }

  if (IS_MEASUREMENT_DES(des_type)) {
    printf("It's a measurement.\n");
  }

  if (des_type == ANALOG_MEAS_DES_TYPE) {
    printf("It's an analog measurement.\n");
  }

  SysQuit();

  return EXIT_SUCCESS;
}

int GetMeasData ( const char * fd,
meas_data_t * data )
 

Get a measurement's FD characteristics.

Parameters:
fd   Measurement descriptor name.
data   Data store for measurement's characteristic data.

GetMeasData() is a user API call that retrieves a set of measurement characteristics from the real-time tables for a given fd. This function returns information about the specified fd in the format specified by the meas_data_t type. (See ApiTypes.h for details)

Returns:
On successful completion SUCCESS is returned. Otherwise, if an error is encountered then FAILURE is returned and g_api_errno is set to indicate the error.
Example:
#include <stdio.h>
#include <stdlib.h>
#include "ApiTypes.h"

int main(int argc, char **argv)
{
  meas_data_t data;

  SysInit(argv[0], NULL);

  if (GetMeasData("FDNAME", &data) != NULL) {
    printf("Description = %s\n", data.description);
    printf("Units = %s\n", data.units);
    printf("Status = %08x\n", data.status);
  }
  else {
    printf("GetMeasData() call failed!\n");
  }

  SysQuit();

  return EXIT_SUCCESS;
}

See also:
ApiTypes.h

int GetMeasType ( const char * fd )
 

Get the type of a specified measurement descriptor.

Parameters:
fd   Measurement descriptor name.

GetMeasType() is a user API call which returns the descriptor's measurement type from the real-time tables for a specified fd. 

The value is returned can be equated to one of the following defines declared in KConstants.h:

        ANALOG_TYPE
        BYTE_ARRAY_TYPE
        DISCRETE_TYPE
        SIGNED_INT_TYPE
        UNSIGNED_INT_TYPE

        ANALOG_PREDEF_TYPE
        BYTE_ARRAY_PREDEF_TYPE
        DISCRETE_PREDEF_TYPE
        SIGNED_INT_PREDEF_TYPE
        UNSIGNED_INT_PREDEF_TYPE


In addition, the following macro has been defined in KConstants.h:

        IS_PREDEFINED_MEAS(meas_type)

        The macro evaluates to true or false (1 or 0)

Returns:
GetMeasType() returns the measurement type, or if an error is encountered then FAILURE is returned and g_api_errno is set to indicate the error.
Example:
#include <stdio.h>
#include <stdlib.h>
#include "ApiTypes.h"

int main(int argc, char **argv)
{
  int meas_type;

  SysInit(argv[0], NULL);

  meas_type = GetMeasType("MEASUREMENT_FDNAME");
  if (meas_type == FAILURE) {
    printf("Invalid descriptor name specified!\n");
  }

  if (IS_PREDEFINED_MEAS(meas_type)) {
    printf("It's a predefined measurement.\n");
  }

  if (meas_type == ANALOG_TYPE) {
    printf("It's an analog measurement.\n");
  }

  SysQuit();

  return EXIT_SUCCESS;
}

char * GetMeasUnit ( const char * fd,
char * unit )
 

Extract a measurement's engineering unit from the system during run-time.

Parameters:
fd   Measurement descriptor name.
unit   Data store for measurement's engineering units string.

GetMeasUnit() is a user API call which retrieves a measurement's engineering unit from the real-time tables for a given fd in the form of a string.

Returns:
On successful completion a pointer to the unit string is returned, otherwise if an error is encountered then NULL is returned and g_api_errno is set to indicate the error.
Example:
#include <stdio.h>
#include <stdlib.h>
#include "ApiTypes.h"

int main(int argc, char **argv)
{
  char unit[MAX_EU_STR_SIZE];

  if (GetMeasUnit("FDNAME", unit) != NULL) {
    printf("units = %s\n", unit);
  }
  else {
    fprintf(stdout, "GetMeasUnit() call failed!\n");
  }

  SysQuit();

  return EXIT_SUCCESS;
}

int GetMeasValue ( const char * fd,
int format_type,
void * value,
int * status )
 

Get a measurement's current value and status from the system during run-time.

GetMeasValue() is a user API call which returns the measurement's current value and status from the real-time tables for the specified fd.

Parameters:
fd   Measurement descriptor name.
format_type   Measurement value output format specification.
value   Measurement value.
status   Measurement status.

The value is returned as specified by the format_type using the following set of defines declared in ApiTypes.h for each valid format specification: 

For processed data values:
        CHAR_FORMAT   Value size = sizeof(char)
        INT_FORMAT    Value size = sizeof(int)
        LONG_FORMAT   Value size = sizeof(int64_t) // 64-bit Integer
        FLOAT_FORMAT  Value size = sizeof(float)
        DOUBLE_FORMAT Value size = sizeof(double)
        STRING_FORMAT Value size = sizeof(char) * MAX_BYTE_ARRAY_DATA_SIZE

For raw data values:
        RAW_CHAR_FORMAT   Value size = sizeof(char)
        RAW_INT_FORMAT    Value size = sizeof(int)
        RAW_LONG_FORMAT   Value size = sizeof(int64_t) // 64-bit Integer
        RAW_FLOAT_FORMAT  Value size = sizeof(float)
        RAW_DOUBLE_FORMAT Value size = sizeof(double)
        RAW_STRING_FORMAT Value size = 2 * sizeof(char) * MAX_BYTE_ARRAY_DATA_SIZE
                                       (as null terminated HEX string)
        RAW_BYTE_ARRAY_FORMAT Value size =  sizeof(char) * MAX_BYTE_ARRAY_DATA_SIZE

Note:
For discrete measurement types if you request the (processed) string format you get the low/high state string instead of a numerical value.

If the user supplied status parameter is not NULL, then the measurement's current status is copied into this parameter. See MeasStat.h for a description of the current status field and all associated bit masks.

Returns:
Upon successful completion the size of the value parameter (in bytes) is returned, otherwise if an error is encountered then FAILURE is returned and g_api_errno is set to indicate the error.
Example:
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "KSizes.h"
#include "ApiTypes.h"

int main(int argc, char **argv)
{
  char fdname[MAX_FD_SIZE];

  float floatVal;
  int integerVal;
  char discVal;
  char textString[MAX_BYTE_ARRAY_DATA_SIZE];
  int status;

  SysInit(argv[0], NULL);

  strcpy(fdname, "FLOAT_FDNAME");
  if (GetMeasValue(fdname, FLOAT_FORMAT, &floatVal, &status) != FAILURE) {
    printf("%s's value = %f\n", fdname, floatVal);
  }

  strcpy(fdname, "INTEGER_FDNAME");
  if (GetMeasValue(fdname, INT_FORMAT, &integerVal, &status) != FAILURE) {
    printf("%s's value = %d\n", fdname, integerVal);
  }

  strcpy(fdname, "DISCRETE_FDNAME");
  if (GetMeasValue(fdname, CHAR_FORMAT, &discVal, &status) != FAILURE) {
    printf("%s's value = %d\n", fdname, discVal);
  }

  strcpy(fdname, "FLOAT_FDNAME");
  if (GetMeasValue(fdname, STRING_FORMAT, textString, NULL) != FAILURE) {
    printf("%s's value = %s\n", fdname, textString);
  }

  SysQuit();

  return EXIT_SUCCESS;
}

int GetNumCmdMeas ( const char * fd )
 

Get the number of parameters associated with a command from the system during run-time.

Parameters:
fd   Command descriptor name.

GetNumCmdMeas() is a user API call which retrieves the number of command parameters for a given command FD.

Returns:
On successful completion the number of parameters is returned, otherwise if an error is occurs then -1 is returned and g_api_errno is set to indicate the error.
Example:
#include <stdio.h>
#include <stdlib.h>
#include "ApiTypes.h"

int main(int argc, char **argv)
{
  int i;
  char command_fd[MAX_FD_SIZE];

  SysInit(argv[0], NULL);

  strcpy(command_fd, "COMMAND FDNAME");

  i = GetNumCmdMeas(command_fd);
  printf("Command %s has %d parameter(s)\n", command_fd, i);

  SysQuit();

  return EXIT_SUCCESS;
}

See also:
GetCmdMeas()

char * GetProjectName ( char * name )
 

Get the current project's ASCII name.

Parameters:
name   Where the project name will be stored.
Description:
GetProjectName() is a user API call that returns the current project's name.

Returns:
On successful completion a pointer to the project name is returned, otherwise if an error is encountered then NULL is returned and g_api_errno is set to indicate the error.
Example:
#include <stdio.h>
#include <stdlib.h>
#include "ApiTypes.h"

int main(int argc, char **argv)
{
  char project_name[MAX_FILENAME_SIZE];

  SysInit(argv[0], NULL);

  if (GetProjectName(project_name) != NULL) {
    printf("project name = %s\n", project_name);
  }

  printf("project name = %s\n", GetProjectName(project_name));

  SysQuit();

  return EXIT_SUCCESS;
}

int IssueCmd ( const char * fd,
void * command_response_data,
... )
 

Issue a parameterized command.

Parameters:
fd   Command descriptor name.
command_response_data   Command response value.
...   Command parameter data.

IssueCmd() is a user API call which accepts zero or more variable arguments which correspond to command parameter data for the given command fd.

Note:
Care must be taken by the caller to pass in correct data types for the individual command parameters. No caller data will be applied to any command or command parameters that are declared predefined in the real-time tables.

Note:
command_response_data is a data store for the command responses which is returned to the caller. The command response data for any particular command is specific to the process handling the command itself. Currently command response fields are integer values. Generally these contain ACK or NAK values, but may contain more specific codes as seen fit by the command handler.

Returns:
On successful completion SUCCESS is returned, otherwise if an error is encountered then FAILURE is returned and g_api_errno is set to indicate the error.
Example:
#include <stdio.h>
#include <stdlib.h>
#include "ApiTypes.h"

int main(int argc, char **argv)
{
  int response_data1[4];
  int response_data2;
  int rtn;

  SysInit(argv[0], NULL);

  rtn = IssueCmd("PREDEFINED_COMMAND_FD", response_data1);
  printf("response data = %d\n", *(int *)response_data1);

  rtn = IssueCmd("COMMAND_FD", &response_data2);
  printf("response data = %d\n", response_data2);

  SysQuit();

  return EXIT_SUCCESS;
}

See also:
IssueValue()

int IssueValue ( const char * fd,
int format_type,
void * value,
void * command_response_data )
 

Issue a command with value.

Parameters:
fd   Command descriptor name.
format_type   Command value input format specification.
value   Command value.
command_response   Command response value.

IssueValue() is a user API call, similar to IssueCmd(), which accepts exactly one argument which corresponds to the single command parameter for the given command fd.

Unlike the IssueCmd() API, IssueValue() expects a format_type similar to the SetMeasValue() API function. This format specification identifies the data type of the command value to issue.

This allows the flexibility to issue commands with a parameter value that doesn't necessarily correspond to the format expected by the command fd. With the exception that commands issued through this API call can only have one parameter.

Refer to both IssueCmd() and SetMeasValue() for information regarding the command_response_data and format_type arguments respectively.

Returns:
On successful completion SUCCESS is returned, otherwise if an error occurs then FAILURE is returned and g_api_errno is set to indicate the error.
Example:
#include <stdio.h>
#include <stdlib.h>
#include "ApiTypes.h"

int main(int argc, char **argv)
{
  int value;
  int response_data;
  int rtn;

  SysInit(argv[0], NULL);

  value = 5;

  rtn = IssueValue("COMMAND_FD", INT_FORMAT, &value, &response_data);

  if (rtn != FAILURE) {
    printf("response data = %d\n", response_data);
  }

  SysQuit();

  return EXIT_SUCCESS;
}

See also:
IssueCmd() , SetMeasValue()

int SetMeasValue ( const char * fd,
int format_type,
void * value )
 

Set a measurement's processed or raw value during run-time.

Parameters:
fd   Measurement descriptor name.
format_type   Measurement value input format specification.
value   Measurement value.

SetMeasValue() is a user API call that sets the measurement's processed or raw value from user input for a specified fd.

The value passed in is specified by the format_type using the following set of defines declared in ApiTypes.h for each valid format specification: 

For processed input values:</EM><BR>
        CHAR_FORMAT       Value size = sizeof(char)
        INT_FORMAT        Value size = sizeof(int)
        LONG_FORMAT       Value size = sizeof(int64_t) // 64-bit Integer
        FLOAT_FORMAT      Value size = sizeof(float)
        DOUBLE_FORMAT     Value size = sizeof(double)
        STRING_FORMAT     Value size = strlen(string)
                                       (as null terminated string)
        BYTE_ARRAY_FORMAT Value size = sizeof(int) size field
                          (self contained first integer field of byte array)

For raw input values:
        RAW_CHAR_FORMAT       Value size = sizeof(char)
        RAW_INT_FORMAT        Value size = sizeof(int)
        RAW_LONG_FORMAT       Value size = sizeof(int64_t) // 64-bit Integer
        RAW_FLOAT_FORMAT      Value size = sizeof(float)
        RAW_DOUBLE_FORMAT     Value size = sizeof(double)
        RAW_STRING_FORMAT     Value size = strlen(string)
                              (as null terminated string)
        RAW_BYTE_ARRAY_FORMAT Value size = sizeof(int) size field
                              (self contained first integer field of byte array)

Returns:
On successful completion SUCCESS is returned, otherwise if an error is encountered then FAILURE is returned and g_api_errno is set to indicate the error.
Example:
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "KSizes.h"
#include "ApiTypes.h"

int main(int argc, char **argv)
{
  float floatVal;
  int integerVal;
  char discVal;
  char textString[MAX_BYTE_ARRAY_DATA_SIZE];

  SysInit(argv[0], NULL);

  SetMeasValue("FLOAT_FDNAME", FLOAT_FORMAT, &floatVal);

  SetMeasValue("INTEGER_FDNAME", INT_FORMAT, &integerVal);

  SetMeasValue("DISCRETE_FDNAME", CHAR_FORMAT, &discVal);

  SetMeasValue("FLOAT_FDNAME", STRING_FORMAT, textString);

  SysQuit();

  return EXIT_SUCCESS;
}

int SysInit ( const char * prog_name,
void(* fp)() )
 

User process initialization.

Parameters:
prog_name   This parameter specifies the title string to be used on the display window.
fp   This parameter specifies which function to call upon receipt of the termination signal. If this parameter is set to NULL, then the SysQuit() function will be called by default. NOTE: The user will be responsible for calling SysQuit() internally if this parameter is not NULL.

SysInit() is the procedure responsible for initializing the user process and attaching the system services. This function must be called prior to any applications command calls or those commands will fail. It is also essential that the error returns from the function be checked to verify initialization was completed successfully.

Returns:
Upon successful completion SUCCESS is returned, otherwise an error notice is logged and FAILURE is returned and g_api_errno is set to indicate the error.
Example:
#include <stdio.h>
#include <stdlib.h>
#include "ApiTypes.h"

int main(int argc, char **argv)
{
  int rtn;

  rtn = SysInit(argv[0], NULL);
  if (rtn == SUCCESS) {
    // all is well
  }
  else {
    // most application functions will not work
  }

  // Done with all CCTK specific application work ...

  SysQuit();

  return EXIT_SUCCESS;
}

See also:
SysQuit()

void SysQuit ( void )
 

Clean up all system internals for the application. SysQuit() is an internal function used to detach the process from all system services.

This function is used by the API function SysInit(). The function does not exit the system, instead only detaches the application from all of the system services to assure proper shutdown from the CCTK environment.

See also:
SysInit()

void api_perror ( const char * s )
 

Print application error messages.

api_perror() produces a message on the standard error output, describing the last error encountered during a call to a application library function. The argument string s is printed first, then a color and a blank, then the message and a newline. (However, if s is a null pointer or points to a null string, the colon is not printed.) The error number is take from the external variable g_api_errno, which is set when errors occur but not cleared when non-erroneous calls are made.

char * api_strerror ( int api_errnum )
 

Get application error message string.

api_strerror() maps the api error number in api_errnum to an error message string, and returns a pointer to that string. api_strerror uses the same set of error messages as api_perror.

Note:
The returned string should not be overwritten.

Variable Documentation

int g_api_errno = 0
 

Error number of the last application error message.

The integer g_api_errno is set by the API library functions when errors occur. The value is significant only when a call returns an error but not cleared when non-erroneous calls are made.

Copyright © 2000 Command and Control Technologies Corporation. All rights reserved.