aida_pva_server_helper.c File Reference

This file contain functions and MACROS that should be used directly Native Channel Providers. More...

#include "apdesc.h"
#include "aida_pva_server_helper.h"

Go to the source code of this file.

Functions
void	aidaThrow (JNIEnv *env, vmsstat_t status, char *exception, const char *message)
	To log any exceptions and throw back to java. More...
void	aidaThrowNonOsException (JNIEnv *env, char *exception, const char *message)
	To log any non-OS exceptions and throw back to java. More...
void *	allocateMemory (JNIEnv *env, void *source, size_t size, bool nullTerminate, char *message)
	Allocate memory and copy the source to it if specified. More...
int	endsWith (const char *str, char *suffix)
	Check if a string str, ends with another string suffix. More...
Argument	getArgument (Arguments arguments, char *name)
	Get a named argument. More...
json_value *	getJsonRoot (json_value *jsonValue)
json_value *	getJsonValue (Value *value, char *passedInPath)
	Get the json value from the given value identified by the path. More...
Value	getNamedArrayValue (JNIEnv *env, Arguments arguments, char *name)
	Get value from a named argument in the provided arguments structure. More...
Value	getNamedValue (JNIEnv *env, Arguments arguments, char *name)
	Get value from a named argument in the provided arguments structure. More...
int	groupNameFromUri (char groupName[], const char *uri)
	Get the Display group name from a URI. More...
vmsstat_t	init (const char *processName, bool initMessageServices)
	Call standalone_init() More...
int	pmuFromDeviceName (JNIEnv *env, char *device, char *primary, char *micro, int4u *unit)
	Get primary, micro and unit from a device name. More...
void	pmuStringFromUri (char *pmuString, const char *uri)
	Get the pmu part of a URI. More...
void	secnFromUri (const char *uri, int4u *secn)
	Get secondary from pseudo secondary (containing a colon) number from URI e.g. More...
const char *	secondaryFromUri (const char *uri)
	Get secondary from URI. More...
unsigned long int	STANDALONE_INIT (const struct dsc$descriptor_s *name, const long int *dbinit, const struct msginit *msginit, const long int *query, const long int *set)
	standalone init is used to initialise standalone processes More...
int	startsWith (const char *str, char *prefix)
	Check if a string starts with another string. More...
void	uriLegacyName (char legacyName[MAX_URI_LEN], const char *uri)
	Convert the given URI to the legacy AIDA name for low level functions that still require it that way. More...
void	uriToSlcName (char slcName[MAX_URI_LEN], const char *uri)
	Convert all URIs to slac names before making queries. More...

Detailed Description

This file contain functions and MACROS that should be used directly Native Channel Providers.

These functions provide all of the features that allow the Channel Provider to implement its service.

MEMBER=SLCLIBS:AIDA_PVALIB ATTRIBUTES=JNI

• MACROS to allocate, track and release memory
• Throwing exceptions and determining if one has been thrown
• Argument processing, except ascanf() and avscanf()
• MACROS and functions to construct and decode URIs into their constituent parts

Definition in file aida_pva_server_helper.c.

Function Documentation

aidaThrow()

void aidaThrow	(	JNIEnv *	env,
		vmsstat_t	status,
		char *	exception,
		const char *	message
	)

To log any exceptions and throw back to java.

Exception Handling.

The #exception is formatted in a standard way using the VMS status code and its associated message and the optionally supplied #message. The #exception is always assumed to be from the edu.stanford.slac.except package

Parameters

env	the JNI environment. Used in all functions involving JNI
status	the VMS status code to luck up and display text for.
exception	the string representation of the exception class to throw.
message	the optional message to attach to the exception. If NULL it is ignored.

Definition at line 92 of file aida_pva_server_helper.c.

{
    // Clear any exception that may be in the process of being thrown (unlikely)
    if ((*env)->ExceptionCheck(env)) {
        (*env)->ExceptionClear(env);
    }
 
    char vmsErrorMessage[BUFSIZ] = { '\0' };
    $DESCRIPTOR(MESSAGE, vmsErrorMessage);
    struct dsc$descriptor errorMessageDescriptor = { BUFSIZ, DSC$K_DTYPE_T, DSC$K_CLASS_S, (char*)&vmsErrorMessage };
 
    //  Get the message text associated with the VMS message code. if the cause is an OS error
    if (!SUCCESS(status)) {
        ERRTRANSLATE(&status, &errorMessageDescriptor);
        strncat(errorMessageDescriptor.dsc$a_pointer, "; ",
                MIN(strlen("; "), BUFSIZ - strlen(errorMessageDescriptor.dsc$a_pointer)));
    }
 
    // Add exception
    strncat(errorMessageDescriptor.dsc$a_pointer, exception,
            MIN(strlen(exception), BUFSIZ - strlen(errorMessageDescriptor.dsc$a_pointer)));
 
    // If a message is specified then append it to the vms message string
    if (message) {
        strncat(errorMessageDescriptor.dsc$a_pointer, "; ",
                MIN(strlen("; "), BUFSIZ - strlen(errorMessageDescriptor.dsc$a_pointer)));
        strncat(errorMessageDescriptor.dsc$a_pointer, message,
                MIN(strlen(message), BUFSIZ - strlen(errorMessageDescriptor.dsc$a_pointer)));
    }
 
    fprintf(stderr, "AIDA Exception: %s: %s\n", exception, errorMessageDescriptor.dsc$a_pointer);
 
    // Create the fully qualified java class name of the exception to throw
    char classToCreate[BUFSIZ] = "edu/stanford/slac/except/";
    strcat (classToCreate, exception);
 
    // Create the java exception class
    jclass exceptionClass;
    exceptionClass = (*env)->FindClass(env, classToCreate);
    if (!exceptionClass) {
        fprintf(stderr, "FATAL: Failed to create object of class: %s\n", classToCreate);
        exit((int)status);
    }
 
    //  Throw the given exception to Java server code, giving the
    //  VMS error text and supplied message as the exception text.
    (*env)->ThrowNew(env, exceptionClass, errorMessageDescriptor.dsc$a_pointer);
}

Referenced by aidaRequestBoolean(), aidaRequestBooleanArray(), aidaRequestByte(), aidaRequestByteArray(), aidaRequestDouble(), aidaRequestDoubleArray(), aidaRequestFloat(), aidaRequestFloatArray(), aidaRequestInteger(), aidaRequestIntegerArray(), aidaRequestLong(), aidaRequestLongArray(), aidaRequestShort(), aidaRequestShortArray(), aidaRequestString(), aidaRequestTable(), aidaServiceInit(), aidaSetValue(), aidaSetValueWithResponse(), and aidaThrowNonOsException().

aidaThrowNonOsException()

void aidaThrowNonOsException	(	JNIEnv *	env,
		char *	exception,
		const char *	message
	)

To log any non-OS exceptions and throw back to java.

The #exception is formatted in a standard way with the optionally supplied #message. The #exception is always assumed to be from the edu.stanford.slac.except package

Parameters

env	the JNI environment. Used in all functions involving JNI
exception	the string representation of the exception class to throw.
message	the optional message to attach to the exception. If NULL it is ignored.

Definition at line 75 of file aida_pva_server_helper.c.

{
    aidaThrow(env, 1, exception, message);
}

References aidaThrow().

Referenced by aidaRequestBoolean(), aidaRequestBooleanArray(), aidaRequestByte(), aidaRequestByteArray(), aidaRequestDouble(), aidaRequestDoubleArray(), aidaRequestFloat(), aidaRequestFloatArray(), aidaRequestInteger(), aidaRequestIntegerArray(), aidaRequestLong(), aidaRequestLongArray(), aidaRequestShort(), aidaRequestShortArray(), aidaRequestString(), aidaRequestStringArray(), aidaRequestTable(), aidaSetValue(), aidaSetValueWithResponse(), allocateMemory(), getClassAndValueOfMethod(), newObject(), newObjectFromClass(), pmuFromDeviceName(), tableAddColumn(), tableAddField(), tableAddLabel(), tableCreate(), toBoolean(), toBooleanArray(), toByte(), toByteArray(), toDouble(), toDoubleArray(), toFloat(), toFloatArray(), toInteger(), toIntegerArray(), toLong(), toLongArray(), toShort(), toShortArray(), toStringArray(), and toTable().

allocateMemory()

void * allocateMemory	(	JNIEnv *	env,
		void *	source,
		size_t	size,
		bool	nullTerminate,
		char *	message
	)

Allocate memory and copy the source to it if specified.

Memory Handling.

If the null terminate flag is set null terminate the allocate space, at the last position

Parameters

env	to be used to throw exceptions using aidaThrow() and aidaThrowNonOsException()
source	source of data to copy to newly allocated space, NULL to not copy
size	the amount of space to allocate
nullTerminate	true to null terminate
message	the message to display if anything goes wrong

Returns

the allocated memory

Definition at line 629 of file aida_pva_server_helper.c.

{
    void* data = malloc(size);
    if (!data) {
        aidaThrowNonOsException(env, AIDA_INTERNAL_EXCEPTION, message);
        return NULL;
    }
    if (source) {
        memcpy(data, source, size - (nullTerminate ? 1 : 0));
        if (nullTerminate) {
            *(char*)((char*)data + size - 1) = 0x0;
        }
    }
    return data;
}

References AIDA_INTERNAL_EXCEPTION, and aidaThrowNonOsException().

endsWith()

int endsWith	(	const char *	str,
		char *	suffix
	)

Check if a string str, ends with another string suffix.

String Handling.

Parameters

str	the string to check.
suffix	the suffix to look for at the end of str

Returns

true if str ends with suffix. false

Definition at line 148 of file aida_pva_server_helper.c.

{
    if (!str || !suffix) {
        return false;
    }
    size_t lenstr = strlen(str);
    size_t lenSuffix = strlen(suffix);
    if (lenSuffix > lenstr)
        return false;
    return !strncasecmp(str + lenstr - lenSuffix, suffix, lenSuffix);
}

Referenced by aidaRequestBoolean(), aidaRequestBooleanArray(), aidaRequestByte(), aidaRequestByteArray(), aidaRequestDouble(), aidaRequestDoubleArray(), aidaRequestFloat(), aidaRequestFloatArray(), aidaRequestInteger(), aidaRequestIntegerArray(), aidaRequestLong(), aidaRequestLongArray(), aidaRequestShort(), aidaRequestShortArray(), aidaRequestString(), aidaRequestStringArray(), aidaRequestTable(), and aidaSetValueWithResponse().

getArgument()

Argument getArgument	(	Arguments	arguments,
		char *	name
	)

Get a named argument.

Parameters

arguments	arguments
name	name

Returns

Argument

Definition at line 184 of file aida_pva_server_helper.c.

{
    Argument noArgument;
    memset(&noArgument, 0, sizeof(Argument));
 
    for (int i = 0; i < arguments.argumentCount; i++) {
        Argument argument = arguments.arguments[i];
        if (!strcasecmp(argument.name, name)) {
            if (strlen(argument.value) > 0) {
                return argument;
            }
        }
    }
    return noArgument;
}

References Arguments::argumentCount, Arguments::arguments, Argument::name, and Argument::value.

getJsonRoot()

json_value * getJsonRoot

(

json_value *

jsonValue

)

Skip root element if it is _array otherwise return unchanged

This is because our json parser can't process arrays at the top level and so we insert
an object at the top level with an "_array" element if we find an array at the top level

Parameters

jsonValue

the json value traverse

Returns

json value

Definition at line 404 of file aida_pva_server_helper.c.

{
    if (jsonValue->type == json_object && jsonValue->u.object.length == 1
            && strcmp(jsonValue->u.object.values[0].name, "_array") == 0) {
        jsonValue = jsonValue->u.object.values[0].value;
    }
    return jsonValue;
}

Referenced by getJsonValue().

getJsonValue()

json_value * getJsonValue	(	Value *	value,
		char *	passedInPath
	)

Get the json value from the given value identified by the path.

Parameters

value	the given value
passedInPath	is an absolute reference to the element within the json of the given value. e.g. root.collection.[0].name

Returns

pointer to the json_value

Definition at line 347 of file aida_pva_server_helper.c.

{
    if (value->type != AIDA_JSON_TYPE || !value->value.jsonValue) {
        return NULL;
    }
 
    json_value* jsonValue = getJsonRoot(value->value.jsonValue);
 
    // If there is no path then we already have the json value
    if (!passedInPath || strlen(passedInPath) == 0) {
        return jsonValue;
    }
 
    // can't use const for strtok
    char path[strlen(passedInPath) + 1];
    strcpy(path, passedInPath);
 
    int len;
    char name[256];
    char* arrayRef;
 
    // Extract the first token
    char* token = strtok(path, ".");
 
    while (token) {
        if (*token == '[') {
            // if array is at top level
            jsonValue = processArrayReference(jsonValue, token);
        } else if ((arrayRef = strstr(token, "["))) {
            // element followed by array ref
            len = (int)(arrayRef - token);
            strncpy(name, token, len);
            name[len] = 0x0;
            jsonValue = navigateToObjectElement(jsonValue, name);
 
            jsonValue = processArrayReference(jsonValue, arrayRef);
        } else {
            // element only
            jsonValue = navigateToObjectElement(jsonValue, token);
        }
 
        // Next token
        token = strtok(NULL, ".");
    }
 
    return jsonValue;
}

References AIDA_JSON_TYPE, getJsonRoot(), ValueContents::jsonValue, Value::type, and Value::value.

getNamedArrayValue()

Value getNamedArrayValue	(	JNIEnv *	env,
		Arguments	arguments,
		char *	name
	)

Get value from a named argument in the provided arguments structure.

Get array value from a named argument in the provided arguments structure.

Parameters

env	the JNI environment. Used in all functions involving JNI
arguments	provided arguments structure
name	provided name

Returns

the extracted Value

Definition at line 335 of file aida_pva_server_helper.c.

{
    return getNamedValueImpl(env, arguments, name, true);
}

Referenced by getArrayValue().

getNamedValue()

Value getNamedValue	(	JNIEnv *	env,
		Arguments	arguments,
		char *	name
	)

Get value from a named argument in the provided arguments structure.

Parameters

env	the JNI environment. Used in all functions involving JNI
arguments	provided arguments structure
name	provided name

Returns

the extracted Value

Definition at line 322 of file aida_pva_server_helper.c.

{
    return getNamedValueImpl(env, arguments, name, false);
}

Referenced by getValue().

groupNameFromUri()

int groupNameFromUri	(	char	groupName[],
		const char *	uri
	)

Get the Display group name from a URI.

URI Handling for group, secn, pmu and slacName.

Parameters

groupName	pre-allocated space to store the group name
uri	the new format AIDA PV name

Returns

EXIT_SUCCESS if all goes well EXIT_FAILURE otherwise

Definition at line 472 of file aida_pva_server_helper.c.

{
    strcpy(groupName, uri);
    char* groupNameEnd = strrchr(groupName, ':');
    if (groupNameEnd) {
        *groupNameEnd = 0x0;
    }
    return EXIT_SUCCESS;
}

init()

vmsstat_t init	(	const char *	processName,
		bool	initMessageServices
	)

Call standalone_init()

Initialisation.

Parameters

processName	the name of the process being initialised
initMessageServices	boolean to determine if the message service needs to be initialised

Returns

vms status code

Definition at line 50 of file aida_pva_server_helper.c.

{
    const struct msginit msg_init_s = { 1,      /* init msg service */
                                        1 };    /* init slcnet */
 
    vmsstat_t status;
    $DESCRIPTOR (PROCESS_NAME, processName);    // Ignored in standalone_init() call
 
    status = STANDALONE_INIT(&PROCESS_NAME, &((long)(TRUE)),
            initMessageServices ? &msg_init_s : NULL,
            &((long)(FALSE)), &((long)(FALSE)));
 
    return status;
}

References STANDALONE_INIT().

Referenced by aidaServiceInit().

pmuFromDeviceName()

int pmuFromDeviceName	(	JNIEnv *	env,
		char *	device,
		char *	primary,
		char *	micro,
		int4u *	unit
	)

Get primary, micro and unit from a device name.

Parameters

env	the JNI environment. Used in all functions involving JNI
device	pre-allocated space to store the device
primary	pre-allocated space to store the primary
micro	pre-allocated space to store the micro
unit	pre-allocated space to store the unit

Definition at line 542 of file aida_pva_server_helper.c.

{
    // Copy each part to the provided variables
    char* nextPart = strtok(device, ":");
    unsigned long len;
    if (nextPart) {
        len = strlen(nextPart);
        if (len != 4) {
            aidaThrowNonOsException(env, UNABLE_TO_GET_DATA_EXCEPTION, "Device name is not valid");
            return EXIT_FAILURE;
        }
        memcpy(primary, nextPart, PRIM_LEN);
        nextPart = strtok(NULL, ":");
        if (nextPart) {
            len = strlen(nextPart);
            if (len != 4 || !isdigit(nextPart[2]) || !isdigit(nextPart[3])) {
                aidaThrowNonOsException(env, UNABLE_TO_GET_DATA_EXCEPTION, "Device name is not valid");
                return EXIT_FAILURE;
            }
            memcpy(micro, nextPart, MICRO_LEN);
            nextPart = strtok(NULL, ":");
            if (nextPart) {
                len = strlen(nextPart);
                if (len < 1 || len > 4 || !isdigit(nextPart[0]) || (len > 1 && !isdigit(nextPart[1]))
                        || (len > 2 && !isdigit(nextPart[2])) || (len > 3 && !isdigit(nextPart[3]))) {
                    aidaThrowNonOsException(env, UNABLE_TO_GET_DATA_EXCEPTION, "Device name is not valid");
                    return EXIT_FAILURE;
                }
                *unit = (int4u)atol(nextPart);
            }
        }
    }
    return EXIT_SUCCESS;
}

References aidaThrowNonOsException(), MICRO_LEN, PRIM_LEN, and UNABLE_TO_GET_DATA_EXCEPTION.

Referenced by aidaRequestTable().

pmuStringFromUri()

void pmuStringFromUri	(	char *	pmuString,
		const char *	uri
	)

Get the pmu part of a URI.

Parameters

pmuString	the pre-allocated space to store the pmu string
uri	the new format AIDA PV name

Definition at line 523 of file aida_pva_server_helper.c.

{
    unsigned long pmuEnd = strrchr(uri, ':') - uri;
    if (pmuEnd >= MAX_URI_LEN) {
        pmuEnd = MAX_URI_LEN - 1;
    }
    strncpy(pmuString, uri, pmuEnd);
    pmuString[pmuEnd] = 0x0;
}

References MAX_URI_LEN.

secnFromUri()

void secnFromUri	(	const char *	uri,
		int4u *	secn
	)

Get secondary from pseudo secondary (containing a colon) number from URI e.g.

Get secondary from pseudo secondary (containing a colon) number from URI.

BD01:BEND:BDES => BEND as int4u

Parameters

uri	the new format AIDA PV name
secn	pointer to an int to store the secondary as a number

Definition at line 489 of file aida_pva_server_helper.c.

{
    char uriCopy[strlen(uri) + 1];
    strcpy(uriCopy, uri);
    char* secondary = strrchr(uriCopy, ':');
    if (secondary) {
        memcpy(secn, secondary + 1, sizeof(int4u));
        return;
    }
    fprintf(stderr, "Warning: Found corrupt URI when trying to extract secn: %s\n", uri);
    *secn = 0;
}

secondaryFromUri()

const char * secondaryFromUri

(

const char *

uri

)

Get secondary from URI.

Just points into the URI so don't go messing with it

Parameters

uri	the new format AIDA PV name

Definition at line 507 of file aida_pva_server_helper.c.

{
    char* secondary = strrchr(uri, ':');
    if (!secondary) {
        fprintf(stderr, "Warning: Secondary not found in uri: %s\n", uri);
        return uri;
    }
    return secondary + 1;
}

Referenced by aidaRequestStringArray().

STANDALONE_INIT()

unsigned long int STANDALONE_INIT	(	const struct dsc$descriptor_s *	name,
		const long int *	dbinit,
		const struct msginit *	msginit,
		const long int *	query,
		const long int *	set
	)

standalone init is used to initialise standalone processes

Parameters

name	process name
dbinit	dbinit
msginit	msginit
query	query
set	set

Returns

status

Referenced by init().

startsWith()

int startsWith	(	const char *	str,
		char *	prefix
	)

Check if a string starts with another string.

Parameters

str
prefix

Returns

true if string starts with prefix

Definition at line 166 of file aida_pva_server_helper.c.

{
    if (!str || !prefix) {
        return false;
    }
    size_t lenstr = strlen(str);
    size_t lenPrefix = strlen(prefix);
    if (lenPrefix > lenstr)
        return false;
    return !strncasecmp(str, prefix, lenPrefix);
}

Referenced by aidaRequestLong(), aidaRequestShort(), aidaRequestString(), aidaRequestStringArray(), and aidaSetValue().

uriLegacyName()

void uriLegacyName	(	char	legacyName[MAX_URI_LEN],
		const char *	uri
	)

Convert the given URI to the legacy AIDA name for low level functions that still require it that way.

Parameters

legacyName	pointer to space to store the legacy AIDA name
uri	the new format AIDA PV name

Definition at line 599 of file aida_pva_server_helper.c.

{
    char* firstSeparator = strchr(uri, ':');
    char* secondSeparator = strchr(firstSeparator + 1, ':');
    char* lastSeparator = strrchr(uri, ':');
    // See how many colons.  If only three then this is a pseudo and we need to separate after first
    if (lastSeparator == secondSeparator) {
        // This has only three parts so separate at first colon
        memcpy(legacyName, uri, firstSeparator - uri);
        memcpy(legacyName + (firstSeparator - uri), "//", 2);
        strcpy(legacyName + (firstSeparator - uri) + 2, firstSeparator + 1);
    } else {
        // Normal URI separate at last colon
        memcpy(legacyName, uri, lastSeparator - uri);
        memcpy(legacyName + (lastSeparator - uri), "//", 2);
        strcpy(legacyName + (lastSeparator - uri) + 2, lastSeparator + 1);
    }
}

uriToSlcName()

void uriToSlcName	(	char	slcName[MAX_URI_LEN],
		const char *	uri
	)

Convert all URIs to slac names before making queries.

Parameters

slcName	pointer to space to store the SLC name
uri	the new format AIDA PV name

Definition at line 583 of file aida_pva_server_helper.c.

{
    char* separator = strrchr(uri, ':');
    if (separator) {
        memcpy(slcName, uri, separator - uri);
        memcpy(slcName + (separator - uri), ".", 1);
        strcpy(slcName + (separator - uri) + 1, separator + 1);
    }
}