amaru_add_gen
Call this subroutine to add alarm generation information to the current IPC buffer. It is the responsibility of the application program to allocate space for the message buffer. The routine may be called repeatedly to load multiple alarm generation segments into the message buffer.
Syntax
int amaru_add_gen (bodyptr, bodylen, first_seg,
alarm_id, fr_id, user_or_serv_id,
ref_id, resp_type, key, msg_field,
num_fields, reset_follows, ret_stat);
char *bodyptr;
int bodylen;
COR_BOOLEAN first_seg;
char alarm_id[LONG_NAME_LEN+1];
char fr_id[FR_ID_LEN+1];
char user_or_serv_id[COR_MAX(USER_ID_LEN, SERVICE_ID_LEN)+1];
char ref_id[AM_REF_ID_LEN+1];
AM_RESP_TYPE resp_type;
AM_RESP_KEY key;
AM_MSG_FIELD msg_field[];
int num_fields;
COR BOOLEAN reset_follows;
COR_STATUS *ret_stat;
Input arguments
bodyptr | Pointer to the beginning of the message body of the IPC buffer. |
bodylen | Maximum length of the message body. |
first_seg | Boolean value specifying whether the current generation request should be the first request in the message. TRUE implies first segment. |
alarm_id | Identifier of the alarm to be generated. |
fr_id | Identifier of the factory resource for which the alarm is being generated. |
user_or_serv_id | Used for labeling logged alarms. Usually this is the service_id of the sending process. The AMAP sends the user_id of the connected terminal. |
ref_id | Used to specify unique alarms when multiple alarm definitions are generated for the same Factory Resources. Alarm uniqueness is defined by the combination of alarm_id, fr_id , and ref_id . |
Note: The
ref_id
is not displayed directly on the Alarm Manager User Interface. The
ref_id
, when used, can be duplicated in a message field for display.
|
|
resp_type | Used to select the type of response desired from the AMRP. The application program has three choices: |
AM_CAPTURED_RESP - AMRP responds once the message has been captured (sent to a slave process or journalled). | |
AM_FULL_RESP - AMRP responds once the message has been fully processed. A status segment is returned for each request in the original message. | |
AM_NO_RESP - No response from AMRP to indicate that an alarm message has been received. | |
Note: Only the
resp_type
in the first generation message of each segment is used. Therefore, it is not possible to intermix the type of responses desired within a single IPC message..
|
|
key | The key is useful when the resp_type is set to AM_FULL_RESP. The key allows the application program to match the status segments returned with the alarm generation/update requests. The key is specified by the application program and is returned "as is" by the AMRP. |
msg_field |
Pointer to the beginning of an array containing variable parameter information for the particular alarm. Each element of the array contains a type specifier and the actual field value. The structure AM_MSG_FIELD and the valid field types can be found in the include file
inc_path/
am_defs.h
.
|
num_fields | The number of variable fields in the msg_field array. There is a maximum of AM_MAX_FIELDS. Each element consists of a type specifier and the actual information. |
reset_follows | Set to TRUE to indicate that on acknowledgment, the application will update the alarm message, clear the alarm, and retain the acknowledgment. Otherwise, set to FALSE. |
Output Arguments
ret_stat | Pointer to status structure. |
Return Value
Either COR_SUCCESS, or COR_FAILURE. If the function returns anything other than COR_SUCCESS, additional error information can be found in ret_stat.err_msg and ret_stat.err_code .
amaru_add_gen does not directly generate error codes. It passes the status set by the message formatting routines back to the calling program. The error codes are defined in the include file inc_path/am_errors.h .
When an error occurs, the value of ret_stat.status is COR_FAILURE. ret_stat.err_source and ret_stat.err_code can be used to determine the type of error.
If the source is COR_MF_ERR and the code is MF_INSUF_SPACE, the alarm generation information is not added as the message is full. The application program should call amaru_send_msg , reset first_seg to TRUE, and then add the information to the now empty buffer.