This function defines the logical ordering of elements in the tree.

Syntax:

int (*compare_fnt)(void *, void *)

Arguments:

• First: A void pointer to the first element.

• Second: A void pointer to the second element.

Return values:

• -1: The first element is less than the second element.

• 0: The first element is equal to the second element.

• 1: The first element is greater than the second element.

Example:

int compare(void *e1, void *e2)
{

int c1=*(int *)e1;
int c2=*(int *)e2;
return ((c1==c2)?0:((c1<c2)?-1:1))

}

The self-balancing tree element can contain complex data structures. This function deletes an element from the tree and frees the memory used by that element.

Syntax:

int (*delete_fnt)(void *)

Arguments:

• First: A void pointer to the element to be deleted.

Example:

int delete(void *e1)
{

ASC_free(e1)

}

This function defines an action that will occur at each element of the tree.

Syntax:

int (*action_fnt)(void **, void *, int, int)

Arguments:

• First: A void pointer to the element to be processed.

• Second: A void pointer to the data argument passed to the ASC_walk_SBT function.

• Third: An integer defining the level that the element is on. The root element(s) are on level zero.

• Fourth: An integer defining the order which the element was scanned. Possible values for the fourth argument are:

  • INORDER: Scans all elements in the node then proceeds to the next node.

  • PREORDER: Scans the element and then proceeds to the next node.

  • POSTORDER: Proceeds to the next node and scans the element on the way back.

Return values:

• 0: If you need to continue to walk the rest of the tree.

• 1: If you are finished with the walk.

Example:

int action(void **e1, void *data, int level, int order)
{
if(order==PREORDER)

{
printf("Found(%d) on level(%d) in order(%d) with data(%d)\n", 
**(int **)e1, level, order, *(int *)data);
}

return 0;
}

Defines the search criteria for the find and delete functions.

Syntax:

int (*condition_fnt)(void *, void *)

Arguments:

• First: A void pointer to the element to determine if it meets the search criteria.

• Second: A void pointer to the data argument passed to the ASC_walk_SBT function.

Return values:

• 0: The element does not meet the search criteria.

• 1: The element meets the search criteria.

Example:

int condition(void *e1, void *data)
{

return(*(int *)e1==*(int *)data)

}

This function is the entry point for both ASAP client and server applications. It is called by the relevant API and supplies application-specific logic to the application.

See also appl_cleanup() in client applications.

For more information, see "Multithreaded procedural server initialization."

Syntax:

CS_RETCODE appl_initialize(int argc, char *argv[])

Arguments:

• argc: Number of arguments passed to ASAP on startup.

• argv: Array of character pointers to the arguments themselves.

Return values:

• CS_SUCCEED: Application initialization was successful.

• CS_FAIL: Application initialization failed.

This function invokes ASC_poll() to determine whether a socket is readable and invokes accept() to accept the next client connection request. The file I/O status of the client socket connection is set to be blocking/nonblocking.

The function returns the new socket stream ID associated with the client connection. It is the caller's responsibility to set I/O control options on the socket file descriptor associated with the client connection.

Syntax:

CS_INT ASC_accept (CS_SMALLINT sa_family, CS_INT listen_sockfd, CS_FLOAT accept_timeout)

Arguments:

• sa_family: Specifies address family.

  Valid values are: UNIX_ADDR_FAMILY and INET_ADDR_FAMILY (IMPLINK_ADDR_FAMILY and XEROX_NS_ADDR_FAMILY are not supported.)

• listen_sockfd: Specifies the listener socket file descriptor ID.

• accept_timeout: Specifies the timeout value of the client connect request.

Return values:

• clt_sockfd: Socket file descriptor ID for the newly accepted connection.

This function allocates the memory on the heap and null pads the allocated memory. If it is unable to do so, it issues a diagnostic message and terminates the server.

This function then initializes the allocated memory before returning a pointer to the appropriate memory segment.

See also ASC_free(), ASC_diag().

Syntax:

VOIDPTR ASC_alloc(CS_INT size)

Arguments:

• size: The size, in bytes, of the memory segment to be allocated.

Return values:

• ptr: Void pointer to the allocated initialized memory segment.

This function performs a binary data transfer from the source location to the target location in both clients and servers.

See also srv_bmove(), memcpy().

Syntax:

void ASC_bmove(CS_VOID *source, CS_VOID *target, CS_INT len)

Arguments:

• source: Pointer to the source buffer location.

• target: Pointer to the target location.

• len: Length of the buffer in bytes.

This function offers a common interface to null pad memory areas to both servers and clients.

Syntax:

void ASC_bzero(CS_VOID *ptr, CS_INT len)

Arguments:

• ptr: Pointer to the memory to be null padded.

• len: Length to be padded.

This function allows threads to close a UNIX device.

Syntax:

CS_INT ASC_close(CS_INT dev_fd)

Arguments:

• dev_fd: UNIX file descriptor being closed.

Return values:

• 0: Device closed successfully.

• -1: Device did not close successfully.

This function provides server threads and application clients with the same functionality as the UNIX connect function.

Syntax:

CS_INT ASC_connect(CS_CHAR socket_client, CS_SMALLINT sa_family, CS_CHAR *host_name, CS_CHAR *host_ipaddr, CS_USHORT port)

Arguments:

• socket_client: Specifies whether to connect as socket client or socket server. Valid values are SOCKET_CLIENT, SOCKET_SERVER.

• sa_family: The address family. Valid values are UNIX_ADDR_FAMILY and INET_ADDR_FAMILY (IMPLINK_ADDR_FAMILY and XEROX_NS_ADDR_FAMILY are currently unsupported.)

• host_name: The host name. If connecting to a UNIX domain socket, this argument specifies socket file path.

• host_ipaddr: The host IP address.

• port: The service port number.

Return values:

• 0: Connection to host was successful.

• -1: Connection failed.

This function applies to the correct variable substitution into a specified international message. The message strings are standard C/C++ format strings and are stored in the SARM's database table “tbl_msg_convert". Because the calling function may accept a variable number of arguments (ellipsis notation “..."), there are two methods of accepting data into this function. If the calling function accepts a variable number of arguments, then it must create a va_list and populate it correctly prior to calling this function. If the calling function does not accept a variable number of arguments, then it simply passes NULL to this function and makes use of the ellipsis provided in this function.

See also ASC_convert_msg_user, ASC_imsg_types(), ASC_imsg_types_user(), ASC_load_msg_tbl().

Syntax:

CS_BOOL ASC_convert_msg(CS_CHAR *mbuf, CS_INT bsize, long msg_id, va_list ap, ...)

Arguments:

• mbuf: Message buffer (of at least size ASC_IMBUF_L) to populate.

• bsize: Size of the buffer (ASC_IMBUF_L is recommended as the minimum size) (input) long.

• msg_id ID of the message to post (input).

• va_list_ap: Variable event parameters for the message (NULL or nothing is sufficient for the messages of type ASC_IMES_NOSUBST_T) (input).

Return values:

• CS_TRUE: The function was successfully executed.

• CS_FALSE: An error occurred.

Example:

void sample_with_va_list(CS_INT msg_id, ...)
{

/*
** The dot dot dot above will be processed and
passed as argument into ASC_convert_msg.
** As developers, we do not know how many 
arguments are passed.
*/
va_list ap;
CS_CHAR receive_buffer[MAX_BUFFER_SIZE];
va_start(ap,msg_id);
ASC_msg_convert(receive_buffer , MAX_BUFFER_SIZE ,
msg_id , ap);
va_end(ap);
ASC_diag(NULL , LOW_LEVEL , "sample with va list" ,
__LINE__ , __FILE__ , "returned buffer =
[%s]",receive_buffer);
return;

}
void sample_without_va_list(CS_INT msg_id, CS_INT param1, CS_CHAR *param2, CS_REAL param3, CS_CHAR param4)
{

/*
** The parameters above (param1, param2, param3,
param4) are fixed and must be defined.  They will
be passed
** directly into ASC_convert_msg
*/
CS_CHAR receive_buffer[MAX_BUFFER_SIZE];
ASC_msg_convert(receive_buffer , MAX_BUFFER_SIZE ,
msg_id , NULL, param1, param2, param3, param4);
ASC_diag(NULL , LOW_LEVEL , "sample without va
list" , __LINE__ , __FILE__ , "returned buffer =
[%s]",receive_buffer);

return;

This function is similar to ASC_convert_msg function, except that programmers can define their own message table.

See also ASC_convert_msg, ASC_imsg_types(), ASC_imsg_types_user(), ASC_load_msg_tbl().

Syntax:

CS_BOOL ASC_convert_msg_user(SRQ_MSG_TBL *user_msg_tbl, CS_INT user_msg_tbl_count, CS_CHAR *mbuf, CS_INT bsize, long msg_id, ...)

Arguments:

• user_msg_tbl: List of messages contents to be expanded (input).

• user_msg_tbl_count: Size of messages contents list (input).

• mbuf: Message buffer (of at least size ASC_IMBUF_L) to populate (output).

• bsize: Size of the buffer (ASC_IMBUF_L is recommended as the minimum size) (input) long.

• msg_id: ID of the message to post (input).

Return values:

• CS_TRUE: The function was successfully executed.

• CS_FALSE: An error occurred.

This function allocates and initializes a CLIENT_PROC structure. This function does not open connections to the server.

The configuration parameter USE_GLOBAL_CONTEXT determines whether the global context is used or a separate context is allocated for each connection.

See also ASC_cpopen, ASC_cpfree.

Syntax:

CLIENT_PROC *ASC_cpalloc(CS_CHAR *srv_name, CS_CHAR *userid, CS_CHAR *password)

Arguments:

• srv_name: Name of the server to be used in the connection.

• userid: User ID to establish the connection to the server.

• password: Password to establish the connection to the server.

  Return values:

  • NULL: The function failed and the client process structure could not be allocated.

  • CLIENT_PROC *: Pointer to the CLIENT_PROC structure that was allocated and initialized.

This function checks the network connection to verify that the server is available.

Syntax:

CS_RETCODE ASC_cpcheck(CLIENT_PROC *cp)

Arguments:

• cp: Pointer to the client process structure that is managing the connection.

Return values:

• CS_SUCCEED: Server connection is established and available for processing.

• CS_FAIL: The server connection is not available.

This function closes the connection associated with the client process.

See also ASC_cpopen, ASC_cpfree.

Syntax:

CS_RETCODE ASC_cpclose(CLIENT_PROC *cp)

Arguments:

• cp: Pointer to the client process structure that is managing the connection.

Return values:

• CS_SUCCEED: Connection to the server was successfully closed.

• CS_FAIL: The function failed and the server connection was not closed.

This function disconnects from the server and frees the client process structure (if applicable).

See also ASC_cpalloc, ASC_cpclose.

Syntax:

void ASC_cpfree(CLIENT_PROC *cp)

Arguments:

• cp: Client process structure allocated with ASC_cpalloc.

This function opens a connection to the server that is specified by the client process structure.

See also ASC_cpalloc, ASC_cpclose.

Syntax:

CS_RETCODE ASC_cpopen(CLIENT_PROC *cp)

Arguments:

• cp: Pointer to the client process structure that is managing the connection.

Return values:

• CS_SUCCEED: Connection to the server has been established.

• CS_FAIL: The function failed and the server connection was not created.

When an open server is terminated for any reason, the connections to and from that server are marked as dead (triggers the connection to be closed upon the next use of the connection).

The data structure does not have to be freed and reallocated, because a call to ASC_CPOPEN re-establishes the connection that was marked as dead or closed. It is recommended that you explicitly close the connection with ASC_CPCLOSE before opening the connection again.

This function executes an RPC or registered procedure on the server and processes the results. The results returned by the server are mapped and then the appropriate result handler is called to process the data. If no handler is specified, a default handler provided by the API is executed.

For an example of how to use ASC_cprpcexec, see appl_init.c in $ASAP_BASE/samples.

Syntax:

CS_RETCODE ASC_cprpcexec(CLIENT_PROC *cp, CS_VOID *data, CLIENT_HANDLER *hand_tbl, CM_RPC *rpcdef, ...)

Arguments:

• cp: Pointer to the client process structure that manages the connection.

• data: Generic data pointer that is passed to the handlers once the results are returned by the server.

• hand_tbl: Result handler table for processing the return data.

• rpcdef: RPC definition structure specifying the RPC to be executed and its associated parameters.

• ...: Variable parameter list specifying the values for the RPC parameters identified by rpcdef. All parameters must be pointers.

Return values:

• CS_SUCCEED: RPC execution was successful and the results were handled successfully.

• CS_FAIL: The function failed due to an RPC execution error or one of the result handlers failed.

This function allocates and initializes a self-balancing tree.

Syntax:

SBT *ASC_create_SBT(char name, int unique, int (*compare_fnt)(void *, void *))

Arguments:

• name: Name of the tree or mutex.

• unique: Variable to determine whether or not all elements in the self-balancing tree should be unique.

• Valid values are 1 (all elements unique) and 0 (duplicate elements permitted)

• compare_fnt: Function that defines the logical ordering of the elements. Valid arguments are First (void pointer to the first element) and Second (void pointer to the second element).

Return values:

• NULL: An error has occurred and the tree was not created.

• pointer to SBT: The tree was successfully created.

• -1: If the first is less than the second element.

• 0: If the first is equal to the second element.

• 1: If the first is greater than the second element.

This function formats the current date and time and inserts the appropriate fields in the CS_DATETIME structure passed to it.

Syntax:

void ASC_cur_dts(CS_DATETIME *dts)

Arguments:

• dts: Pointer to the CS_DATETIME structure that will have its fields updated.

Return the current time in seconds and microseconds since 00:00 Universal Coordinated Time, Jan 1, 1970. It uses the UNIX function call gettimeofday() to get the current time.

Syntax:

CS_FLOAT ASC_cur_tm(void)

Return values:

• Current time: Current time in seconds and milliseconds in floating point representation.

This function finds and deletes an element in the tree. Deleting elements from this tree does not affect the balance of the tree.

See also ASC_delete_index_SBT().

Syntax:

int ASC_delete_element_SBT(SBT *root, void *datac, int (*condition_fnt)(void *, void *), void *datad, int (*delete_fnt)(void **, void *))

Arguments:

• root: Pointer to the tree.

• datac: A void pointer that is passed as the second argument to the condition function.

• condition_fnt: A function defining the criteria to delete an element. The first element found (in any logical order) will be used. Only one element is deleted per function call.

  Arguments:

  • First: Void pointer to the element determines if it meets the search criteria

  • Second: Void pointer to the data argument passed to the ASC_walk_SBT function

  Return values:

  • 0: Element does not meet the search criteria

  • 1: Element meets the search criteria

• datad: A void pointer that is passed as the second argument to the delete function.

• delete_fnt: Delete function which deletes data allocated prior to the insert; for example, if the element is an entire data structure such as a linked list.

Return values:

• 0: No element matched the criteria or the tree is empty.

• 1: An element was deleted.

This function deletes an element from a self-balancing tree (SBT) using the logical ordering of the tree to quickly find the element to delete. The advantage of this delete function over ASC_delete_element_SBT is that it uses the logical ordering and comparison function of the tree to delete an element. This function is therefore more efficient than ASC_delete_element_SBT.

Deleting elements from the tree does not affect the balance of the tree.

Syntax

int ASC_delete_index_SBT(SBT *root, void *element, void *data, int (*delete_fnt)(void **, void *))

Arguments

• root: Pointer to an SBT. This is the tree to delete the element from.

• element: Search node that is used to find the correct element in the SBT to delete. You must populate all of the fields used by the comparison function when the elements are first inserted into the tree.

• data: Pointer that is passed into the delete function. Pass NULL if it is not needed.

• delete_fn: Function pointer used to delete the element from the tree. You must correctly free up all memory that was allocated for this element (such as a link list or another type of data structure.)

This function deallocates and frees memory used by a self-balancing tree. It is not necessary to delete the elements of the tree prior to destroying the tree.

Syntax:

void ASC_destroy_SBT(SBT **root, void *data, int (*delete_fnt)(void **, void *))

Arguments:

• root: Pointer to the tree.

• data: A void pointer that is passed as the second argument to the delete function.

• delete_fnt: Function defining the delete algorithm for each element of the tree. This is useful when the element is an entire data structure such as a link-list or another self-balancing tree.

This function lets you specify a printf() format diagnostic message to be appended to the application's diagnostic file. You may also specify the diagnostic level of the message to be appended to the diagnostic file. If the application's configured diagnostic level is less than or equal to that of the function call, the message will be appended to the diagnostic file. For example, a LOW_LEVEL message will not be written if the server is at SANITY_LEVEL.

See also ASC_event.

You can also call this function with different diagnostic levels throughout the code to denote varying degrees of message logging.

Whenever a PROGRAM_LEVEL or FATAL_LEVEL diagnostic message is logged, the libcontrol ASC_diag() function appends a copy of the message to the application's logfile as well.

The libclient ASC_diag() function writes no message to the client application logfile. The ASC_diag() function is designed for messages that do not exceed the maximum size of 1024 bytes. To display a longer message, use the ASC_diag_format function. This function allows you to customize the presentation of any message (for example, a dump of an incoming message).

The output of the diagnostic file is:

>> 141152:12 : LOW:Routing Table:127: router.c 
Internal Routing Table: Locked Mutex, Id [15] 

The fields in the diagnostic file are:

• >>: Line identifier.

• 141152: The time format in hours, minutes, and seconds (hhmmss).

• 12: The SPID of the thread making the diagnostic function call.

• LOW: The level of the diagnostic message.

• Routing Table: The type character buffer specified in the diagnostic function. This generally indicates the current function being performed.

• 127: The line number in the file at which the log entry was generated.

• router.c: The file from which the log entry was made.

• Internal...: The diagnostic message itself to a maximum diagnostic file size of 3MB. Once the diagnostic file size reaches this limit, the existing file is moved to file.old, and a new diagnostics file started. If this happens again, the original diagnostics file is overwritten. Use the configuration variable, MAX_DIAG_FILE, to specify the application's configuration file that overrides the default size.

For information on configuring diagnostics for Java-based components, see com.mslv.activation.server.Diagnostic in the ASAP Online Reference.

Syntax:

void ASC_diag(VOIDPTR ptr, DIAG_LEVEL level, 

const char *type,
int line, 
const char *file, 
const char *fmt, ...); 

Arguments:

• ptr: VOIDPTR – only used by the debugger within the Interpreter.

• level: The diagnostic level of this particular function call. The possible diagnostic levels are outlined in the enumerated data type DIAG_LEVEL description. See "DIAG_LEVEL abstract data type" for more information.

• type: Character pointer identifying the type or functional origin of the function call. Only the first 15 characters of this function call appear in the diagnostic file.

• line: The line number of the function in the source file, "__LINE__".

• file: The file from which the function was called, "__FILE__".

• fmt: Character pointer to a sprintf() format buffer containing the diagnostic message itself.

• "...": Variable number of parameters following the spintf() format.

Example:

The following code segment is an example of how ASC_diag() can be used by the ASAP Client and/or Server Application for diagnostic purposes.

#include "client.h"
CS_INT SRP_get_wo_revs(ASAP_WO_ID wo_id, ...)
{ 
CS_INT num_rows = -1;
char *diag_buf = "SRP_get_wo_revs";
/* do some processing here */
...;
ASC_diag(NULL, LOW_LEVEL, diag_buf, __LINE__, __FILE__,
"WO: %s, Successfully Retrieved the WO Revisions", wo_id);
return num_rows;
}

You can use this function to generate messages in the diagnostic file of the application. When the function is called, the diagnostic message heading is generated in the log. The specified function is called providing access to the FILE pointer for the diagnostic file. The called function can then generate any message in the diagnostic file.

See also ASC_event.

Syntax:

void ASC_diag_format(VOIDPTR ptr, 

DIAG_LEVEL level, 
const char *type,
int line, 
const char *file,
void ((*format_fn)(FILE *diag_outfile, VOIDPTR ptr)));

Arguments:

• ptr: Pointer to a data segment that is passed into the format_fn as the second argument to allow ASC_diag format to pass information to the format_fn.

• level: The diagnostic level of this particular function call. The possible diagnostic levels are outlined in the enumerated data type DIAG_LEVEL description.

• type: Character pointer identifying the type or functional origin of the function call. Only the first 15 characters of this function call appear in the diagnostic file.

• line: The line number of the function in the source file, "__LINE__".

• file: The file from which the function was called, "__FILE__".

• format_fn: Pointer to the function that is executed to generate a message in the diagnostic file. When the format_fn function is called, it cannot call any other diagnostic functions.

This function is used to determine whether or not the application is currently generating diagnostic messages at the specified level.

Syntax:

CS_BOOL ASC_diag_on(DIAG_LEVEL level)

Arguments:

• level: The diagnostic level to query for.

This function closes the specified socket connection to the host.

Syntax:

CS_RETCODE ASC_disconnect(CS_INT sock_fd)

Arguments:

• sock_fd: UNIX socket file descriptor.

This function converts CS_DATETIME to string datetime format. This function is used primarily to convert datetime formats to strings for insertion into Oracle datetime fields.

Syntax:

ASC_dts_to_str(CS_CHAR * date_str, CS_DATETIME *dts)

Arguments:

• date_str: Pointer to datetime string in the following format: YYYYMMDD 24HH:MM:SS. For example, 20030111 16:04:00. This is the format that the Oracle Server is configured to use and is defined in the set_session database function at login.

• dts: Returned ASAP datetime.

This function converts the parameters into a system event request and saves the event in the Control database. Depending on the event type, a system alarm may be generated.

Message size is limited to 80 bytes.

A system alarm can only be generated as a result of a system event. Therefore, to generate alarms, the corresponding events must be generated. If SYS_TERM is the event type, the application terminates.

For information on configuring event generation for Java-based components, see com.mslv.activation.server.EventLog in the ASAP Online Reference.

Syntax:

void ASC_event(const char *event_type, 

short line, 
const char *file, 
const char *fmt, ...);

Arguments:

• event_type: Specifies the system event to be generated. This code is used to determine the operation to perform from the configuration tables.

• line: Line in source file where system event was generated ("__LINE__").

• file: Source file where system event was generated ("__FILE__").

• fmt: "printf" type format string specifying the cause of the system event.

• "...": Variable number of parameters following the sprintf() format.

This function initializes system events to be stored in the database. Whether this function saves events to the tbl_event_log is determined by the configuration variable DB_EVENT_LOGGING in the ASAP.cfg file.

Possible values for this variable are:

• 1 – Save events to tbl_event_log.

• 0 – Does not save events to tbl_event_log.

If the events are not saved to the database, then alarms cannot be triggered to execute when these events are generated.

Syntax:

CS_RETCODE ASC_event_initialize (void)

This function finds the first element that meets the criteria specified in the ASC_find_init_SBT function. The element that is returned can be accessed directly to change the data. It is recommended that the key fields be left unchanged so that the logical ordering of the tree is not disrupted.

Syntax:

int ASC_find_first_SBT(SBT_FIND *head,

SBT_FIND **current,
void **element)

Arguments:

• head: Pointer to results of the previous ASC_findinit_SBT function. No maintenance is required with this data structure.

• current: Pointer that scans the found records. No maintenance is required with this data structure.

• element: A void pointer that receives the first found element.

Return values:

• 0: No elements were found.

• 1: An element was found.

This function deallocates and frees the memory used by the find functions.

The current variable used in the ASC_find_first_SBT and ASC_find_next_SBT functions is not valid after this function is called and should therefore be set to NULL.

Syntax:

void ASC_find_free_SBT(SBT_FIND **head)

Arguments:

• head: Pointer to the results of previous ASC_findinit_SBT function. No maintenance is required with this data structure.

This function returns an element that matches the search record using the logical ordering of the tree as an index. This function uses the same comparison function as ASC_insert_element_SBT to traverse the tree. To use this function, the programmer must ensure that the unique argument is set for the tree (as defined in ASC_create_index_SBT).

The reason for the uniqueness requirement is that only one record is returned (the first to meet the comparison criteria). A simple way to guarantee the uniqueness of the index field(s) is to set the unique flag when creating the tree and when inserting a record:

if ASC_insert_element_SBT!= NULL then

update record

endif

Syntax:

void *ASC_find_index_SBT(SBT *root,

void *data)

Arguments:

• root: Pointer to the tree to walk.

• data: A void pointer that contains the data structure that is stored in the tree with the indexed field(s) containing the data to find in the tree.

Return values:

• 0: No element was found.

• void *: Pointer to the indexed element that was found.

This function allocates and initializes the find function. This function performs the search on the tree via a tree walk algorithm. To take advantage of the logical ordering of the tree, use ASC_find_index_SBT. Observe the following programming technique:

if ASC_find_init_SBT = 1 then

while ASC_find_next_SBT = 1
process found record
ASC_find_free

else

no record was found

endif

Syntax:

int ASC_find_init_SBT(SBT *root,

SBT_FIND **head,
void *data,
int(*condition_fnt)(void*, void*))

Arguments:

• root: Pointer to the tree to walk.

• head: Pointer that receives the results of the search. The first time that this function is used this variable MUST be set to NULL. Before scanning the tree, ASC_find_init_SBT deletes the previous find results and then passes it to ASC_find_first_SBT and ASC_find_next_SBT.

• data: Void pointer that is passed as the second argument to the condition function.

• condition_fnt: Function that defines the search criteria for the elements.

Return values:

• 0: No elements were found.

• 1: An element was found.

This function finds the next element that meets the criteria specified in the ASC_find_init_SBT function. You do not need to call ASC_find_first_SBT prior to this function.

Syntax:

int ASC_find_next_SBT(SBT_FIND *head,

SBT_FIND **current,
void **element)

Arguments:

• head: Pointer to results of previous ASC_findinit_SBT function. No maintenance is required with this data structure.

• current: Pointer that scans the found records. No maintenance is required with this data structure.

• element: Void pointer that receives the next found element.

Return values:

• 0: No elements were found.

• 1: An element was found.

This function deallocates the memory previously allocated using ASC_alloc(). If it is unable to do so, it issues a system event and terminates the server.

See also ASC_alloc(), ASC_diag().

Syntax:

void ASC_free(VOIDPTR ptr)

Arguments:

• ptr: Void pointer to a memory segment previously allocated with ASC_alloc().

This is a pointer to the command in the current context on the client process structure.

Syntax:

ASC_GET_CMD(cp)

This function references the ASAP.cfg configuration file and returns the value of the requested parameter.

If this type of entry is not present as either an application or global configuration parameter, then the default value is returned.

The configuration variables listed in the configuration file are read initially by the application and stored internally from then on. Any change to the configuration files requires the application to be restarted in order to use the new settings.

Syntax:

CS_RETCODE ASC_get_config_param(char *param, 

char *value, 
char *default_val)

Arguments:

• param: The parameter name itself.

• value: Character pointer to the value of the requested parameter. The returned parameter value is placed in this location.

• default_val: Character pointer to the default value to be used for this parameter if the parameter is not listed in the configuration file.

Return values:

• CS_SUCCEED: Parameter value found in the configuration file or the default value returned.

This is a pointer to the context on the client process structure.

Syntax:

ASC_GET_CONTEXT(cp)

This is a pointer to the server name on the client process structure.

Syntax:

ASC_GET_SERVER(cp)

Gets characters in a non-blocking mode from a stream file. Read timeout is achieved in UNIX code by setting alarm() before calling the getc system call.

The alarm() call cannot be used to time out the call in the ASAP server because the Sleep Manager thread provided by the ASAP Server API uses alarm() to implement sleep management. ASC_getc() calls ASC_poll() to provide timeout. For uniformity, the same approach is followed in the Client API.

See also ASC_poll(), ASC_putc(), UNIX getc(), putc().

The function declaration is the same as for the UNIX getc except for the additional parameter that specifies the timeout in seconds.

This function assumes that the file descriptor has not been set to nonblocking mode.

This function invokes ASC_poll() to check if port is readable. It is not intended to be used to read from disk files.

Syntax:

CS_INT ASC_getc(FILE *stream,

CS_FLOAT timeout)

Arguments:

• stream: Open file descriptor to read from.

• timeout: Timeout in seconds.

Return values:

• c: The character read/written to the stream file.

• -1: A UNIX error occurred on getc/putc.

• -2: ASC_read/ASC_write timed out.

• -3: Port hangup detected.

• -4: EOF returned by getc/putc due to a UNIX error and no port hangup.

This function gives the API a consistent method of calling the gettimeofday() UNIX function.

Syntax:

ASC_gettimeofday(tp, tzp)

By specifying a buffer, length, and diagnostic level similar to ASC_diag(), this function provides a method of generating a hexadecimal dump of the selected buffer in the applications diagnostic logfile.

See also ASC_diag().

Syntax:

void ASC_hex_dump(DIAG_LEVEL level, 

const char *type, 
int line, 
const char *file, 
CS_BYTE *buf, 
int buf_len);

Arguments:

• level: The diagnostic level of the function call. See ASC_diag() for more information.

• type: Brief description of the circumstances of the function call to identify such entries in the applications logfile.

• line: The line in the source file at which the function was called.

• file: The source file from which this function was called.

• buf: The character buffer for which the hexadecimal dump is to be generated.

• buf_len: The length of the buffer.

This function writes the specified binary buffer to a file in hexadecimal format.

Syntax:

void ASC_hex_dump_to_file(FILE *fptr,

CS_BINARY *buf,
int len)

Arguments:

• fptr: File pointer to open destination file for the hex dump.

• buf: Buffer containing the data to be dumped.

• len: Length of the buffer in bytes.

This function determines the formatting mode and destination types of the specified international message.

See also ASC_load_msg_tbl(), ASC_convert_msg().

Syntax:

CS_BOOL ASC_imsg_types(long msg_id, 

CS_CHAR *frm_type,
CS_CHAR *dest_type)

Arguments:

• long msg_id: ID of the message to post (input).

• frm_type: Formatting type (one character long) of the message (may be NULL) (output).

  Substitution type can be one of the following: ASC_IMES_NOSUBST_T, ASC_IMES_SUBST_T, CS_CHAR

• Dest_type: Destination type (one character long) of the message (may be NULL) (output).

  The destination type can be one of the following: ASAP_LOG_SRQ, ASAP_LOG_WOA, ASAP_LOG_SRQWOA, ASAP_LOG_NO

Return values:

• CS_TRUE: On success.

• CS_FALSE: On failure.

This function determines the formatting mode and destination types of the specified international message from a user-defined message table.

See also ASC_load_msg_tbl(), ASC_convert_msg().

Syntax:

CS_BOOL ASC_imsg_types_user(SRQ_MSG_TBL *user_msg_tbl,

CS_INT user_msg_tbl_count,
long msg_id,
CS_CHAR *frm_type,
CS_CHAR *dest_type)

Arguments:

• user_msg_tbl; List of messages contents to be expanded (input).

• user_msg_tbl_count: Size of messages contents list (input).

• long msg_id: ID of the message to post (input).

• frm_type: Formatting type (one character long) of the message (may be NULL) (output).

  Substitution type can be one of the following: ASC_IMES_NOSUBST_T, ASC_IMES_SUBST_T, CS_CHAR

• Dest_type: Destination type (one character long) of the message (may be NULL) (output).

  The destination type can be one of the following: ASAP_LOG_SRQ, ASAP_LOG_WOA, ASAP_LOG_SRQWOA, ASAP_LOG_NO.

Return values:

• CS_TRUE: The function was successfully executed.

• CS_FALSE: An error occurred.

This function inserts an element into the tree. Inserting elements into the tree does not affect the balance of the tree. Therefore, a resort to randomness algorithm is not required on the key fields to improve on the balancing of the tree, as is the case with a binary search tree.

Syntax:

void *ASC_insert_element_SBT(SBT *root,

void *element)

Arguments:

• root: Pointer to the tree to insert into.

• element: A void pointer to the element to be inserted. It is the caller's responsibility to maintain the memory for the element since only a pointer is stored in the tree.

Return values:

• NULL: The node is inserted into the tree.

• not NULL: Pointer to an existing node that matches the key fields of the node to be inserted. No new node was inserted.

This is a boolean flag to determine whether the current connection is open on the client process structure.

Syntax:

ASC_IS_OPEN(cp)

This function switches the Oracle connection between oci8 and oci7.

After obtaining a CLIENT_PROC, using ASC_cppalloc() for example, the ASC_oci8_to_lda bridge API must be called to switch the OCI8 context to OCI7 LDA. Once this is done, the OCI7 wrapping functions (such as ASC_ociopen_cursor(), ASC_ociparse(), ASC_ocirpcexec() and so on) can be used.

Similarly, before freeing a CLIENT_PROC using, for example, ASC_cppfree(cp), the ASC_lda_to_oci8 API must be called to switch OCI7 LDA back to OCI8 context.

If using a high level API like ASC_cprpcexec(), this switching mechanism is not required.

Several high level wrapping functions support one connection-to-cursor array relationships. As a result, ASC_ociopen() does not open a cursor. The function to open a cursor has been moved to ASC_oci8_to_lda(). Without this bridge, the OCI parse call will fail.

Syntax:

CS_RETCODE ASC_oci8_to_lda( CLIENT_PROC *cp)

Arguments:

• cp: Connection to the SARM database.

Return values:

• CS_SUCCEED: Successfully switched an Oracle connection.

• CS_FAIL: Failed to switch an Oracle connection.

This function listens for connection requests on the specified port by invoking the appropriate local function based on the socket address family you specify.

The caller can then invoke ASC_accept() to accept the next incoming client connection request.

Setting socket options is not currently supported by ASC_connect().

Syntax:

CS_INT ASC_listen (CS_SMALLINT sa_family,

CS_CHAR *host_name,
CS_CHAR *host_ipaddr,
CS_USHORT port,
CS_INT backlog)

Arguments:

• sa_family: Specifies the address family. Valid values are: UNIX_ADDR_FAMILY, INET_ADDR_FAMILY. (IMPLINK_ADDR_FAMILY, and XEROX_NS_ADDR_FAMILY are not supported)

• host_name: The host name. If it is a UNIX domain socket, it specifies the socket file path.

• host_ipaddr: The host IP address.

• port: The service port number.

• backlog: The maximum allowable length of the queue for pending connections. If a connection request arrives when the queue is full, the client receives an error.

  Backlog is currently limited by the system (silently) to be in the range of 1 to 20. If any other value is specified, the system automatically assigns the closest value within range.

Return values:

• Listener Socket FID: The socket file descriptor ID that listens for incoming client requests is returned if the call succeeds.

• -1: If the call fails.

This function loads international messages and audit destinations from the SARM database into memory. It executes the function SSP_load_msg_tbl using the requested language code.

Syntax:

CS_BOOL ASC_load_msg_tbl(CLIENT_PROC *cp,

CS_CHAR *lang)

Arguments:

• cp: Connection to the SARM database.

• lang: Language code of messages to be loaded. If NULL, it uses the value of the configuration parameter LANGUAGE_OF_MSG. If the configuration parameter is not defined, it defaults to “USA".

Return values:

• CS_TRUE: The function was successfully executed.

• CS_FALSE: An error occurred.

This function switches the Oracle connection between oci7 and oci8.

Syntax:

CS_RETCODE ASC_oci8_to_lda( CLIENT_PROC *cp)

Arguments:

• cp: Connection to the SARM database.

Return values:

• CS_SUCCEED: Successfully switched an Oracle connection.

• CS_FAIL: Failed to switch an Oracle connection.

This function cancels a query on a cursor after the desired rows have been fetched.

This function is used to free up resources after you have completed processing the required number of rows and there are rows still pending in the result set.

Syntax:

CS_RETCODE ASC_ocican_cursor( Cda_Def  *cda)

Arguments:

• cda: Pointer to a cursor data area structure.

Return values:

• CS_SUCCEED: The function was successfully executed.

• CS_FAIL: The function failed.

This function closes a connection between an Open Server or Open Client and an Oracle database (using oci8 calls).

Syntax:

CS_RETCODE ASC_ociclose(CLIENT_PROC *cp)

Arguments:

• cp: Pointer to the CLIENT_PROC structure to be closed.

Return values:

• CS_SUCCEED: Successfully closed an Oracle connection.

• CS_FAIL: Failed to close an Oracle connection.

This function closes a cursor. It disconnects a cursor from the data areas in the Oracle Server with which it is associated.

Syntax:

CS_RETCODE ASC_ociclose_cursor(Cda_def *cda)

Arguments:

• cda: Pointer to cursor data area structure.

Return values:

• CS_SUCCEED: The function closed the cursor.

• CS_FAIL: The function failed to close the cursor.

This function builds a PL/SQL block from the passed CM_RPC structure. The resulting command is passed to ASC_ociparse to be associated with an open cursor.

Syntax:

CS_RETCODE ASC_ocicreate_cmd(CS_CHAR *command, CM_RPC *rpcdef)

Arguments:

• command: PL/SQL command buffer.

• rpcdef: CM_RPC structure containing RPC name and associated parameters.

Return values:

• CS_SUCCEED: The function successfully built PL/SQL block.

• CS_FAIL: The function to build the PL/SQL block.

To receive a return status from an RPC to the Oracle server, functions are used on the server side instead of procedures. Therefore, all command strings receive a return value.

This function defines an output variable for each column of the result set. This function uses the odescr function to determine the column name, data type, and data size for every column in the cursor variable. After the column information is determined, it is used to populate the call to odefin. The odefin function is required to define the storage array for each column in the result set.

Syntax:

CS_INT ASC_ocicreate_list(CLIENT_PROC *cp, Cda_Def *cda, ORA_COLUMN *colsptr, CS_INT numrows)

Arguments:

• cp: Points to a CLIENT_PROC structure.

• cda: Points to a CDA structure.

• colsptr: Points to an Oracle column structure that is defined while processing the resultant data.

• numrows: The number of rows to allocate in the ORA_COLUMN structure. This parameter governs how many rows are returned with each fetch of the result set.

Return values:

• CS_INT: The number of columns described in the result set.

This function deallocates all memory allocated during the ASC_ocicreate_list function. ASC_ocidestroy_list must accompany each use of ASC_ocicreate_list after processing is complete. If not, these resources will not be available.

Syntax:

CS_RETCODE ASC_ocidestroy_list(ORA_COLUMN *cols)

Arguments:

• cols: Points to an Oracle column structure that was defined while processing the resultant data.

Return Value:

• CS_SUCCEED: The function was successful.

• CS_FAIL: The function failed.

This function attempts to fetch as many rows as were defined by the numrows argument of the function ASC_ocicreate_list.

Syntax:

CS_RETCODE ASC_ocifetch(CLIENT_PROC *cp, Cda_Def *cda, ORA_COLUMN * cols)

Arguments:

• cp: Points to a CLIENT_PROC structure.

• cda: Points to a CDA structure.

• cols: Points to an Oracle column structure that was defined while processing the resultant data.

Return values:

• CS_SUCCEED: Row returned successfully.

• CS_FAIL: No more rows to process.

Opens a single Oracle connection using oci8 calls.

ASC_ociopen() does not open a cursor. The function to open a cursor has been moved to ASC_oci8_to_lda(). Custom code must explicitly call ASC_oci8_to_lda() before parsing. Without this bridge, the OCI parse call will fail.

Syntax:

CS_RETCODE ASC_ociopen(CLIENT_PROC *cp)

Arguments:

• cp: Pointer to the CLIENT_PROC structure to be opened

Return values:

• CS_SUCCEED: Successfully opened an Oracle connection.

• CS_FAIL: Failed to open an Oracle connection.

This function opens a cursor. It associates a cursor data area in the application with a data area in the Oracle server. Cursor data areas are used by Oracle to maintain state information about the processing of a SQL statement.

Syntax:

CS_RETCODE ASC_ociopen_cursor( CLIENT_PROC *cp)

Arguments:

• cp: Pointer to a CLIENT_PROC structure.

Return values:

• CS_SUCCEED: The function opened the cursor.

• CS_FAIL: The function failed to open the cursor.

This function parses a SQL statement or SQL block and associates it with the cursor data area found in CLIENT_PROC member cda. Note that for performance reasons, all parsing is performed in deferred mode. This means that any errors in the command are not detected until the command is executed.

Syntax:

CS_RETCODE ASC_ociparse(CLIENT_PROC *cp, CS_CHAR *command)

Arguments:

• cp: Pointer to a CLIENT_PROC structure.

• command: PL/SQL command.

Return values:

• CS_SUCCEED: The function successfully parsed the PL/SQL block.

• CS_FAIL: The function failed to parse the PL/SQL block.

This function checks the value of the passed CDA to provide error management and diagnostics. In addition, this function is responsible for determining whether the initial OCI call is blocked (due to network, server response etc.) and initiating the synchronous appearance behavior by establishing a poll() on the connection file descriptor found in the CLIENT_PROC member, connection_fd.

Syntax:

CS_VOID ASC_ocistatus(CLIENT_PROC *cp, Cda_Def *cda);

Arguments:

• cp: Pointer to a CLIENT_PROC structure.

• cda: Points to a CDA structure.

Return values:

• CS_SUCCEED: The function was successful.

• CS_FAIL: The function failed.

This function allows threads to open UNIX devices without blocking the application server. It is the thread-level version of the UNIX open system call.

This function is intended to be used to open devices that might potentially block and uses ASC_poll() to check if the port is writable. It is not intended to be used to open disk files.

Syntax:

CS_INT ASC_open(CS_CHAR *path_name,

CS_INT flags,
CS_FLOAT open_timeout)

Arguments:

• path_name: Pathname to the UNIX device being accessed.

• flags: Flags controlling the mode that the device is opened with. The flags used here are analogous to those used in the UNIX “open()" system call.

• open_timeout: Timeout value, in seconds, to wait for the open call to be successful.

Return values:

• >=0: Operation was successful and the UNIX file descriptor is returned.

• -1: Operation failed.

Puts characters in a non-blocking mode to a stream file. Read timeout is achieved in UNIX code by setting alarm() before calling the putc system call.

The alarm() call cannot be used to timeout the call in ASAP server since the Sleep Manager thread provided by ASAP Server API uses alarm() to implement sleep management. ASC_putc() calls ASC_poll() to provide timeout. For uniformity, the same approach is followed in the Client API.

See also ASC_poll(), UNIX getc(), putc().

The function declaration is the same as for the UNIX putc except for the additional parameter that specifies timeout in seconds.

Until all bytes are written or ASC_poll times out, ASC_putc loops the ASC_poll() to check if the port is readable/writable or timed out, and then calls read/write.

This function assumes that the file descriptor has not been set to nonblocking mode.

This function invokes ASC_poll() to check if the port is writable. It is not intended to be used to write to disk files.

Syntax:

CS_INT ASC_putc(CS_INT c,

FILE *stream,
CS_FLOAT timeout)

Arguments:

• stream: Open file descriptor to write to.

• timeout: Timeout in seconds.

Return values:

• c: The character read/wrote to the stream file.

• -1: A UNIX error occurred on getc/putc.

• -2: ASC_read/ASC_write timed out.

• -3: Port hangup detected.

• -4: EOF returned by getc/putc due to a UNIX error and no port hangup.

This function provides timeout using nonblocking read. Read timeout is achieved in UNIX code by setting alarm() before calling a read system call. The alarm() call to timeout the read call cannot be used since the Sleep Manager thread provided by ASAP Server API uses alarm() to implement sleep management. Instead, ASC_read() calls ASC_poll() to provide timeout.

This function assumes that the file descriptor has not been set to nonblocking mode.

This function declaration is the same as for the UNIX read except for the additional parameter that specifies timeout in seconds.

Until all bytes are read or ASC_poll times out, ASC_read loops the ASC_poll() to check if the port is readable or timed out, and then calls ASC_read.

This function is intended to be used to read devices that might potentially block and uses ASC_poll() to check if port is readable. It is not intended to be used to read from disk files.

Syntax:

CS_INT ASC_read(CS_INT fd,

void *buf,
CS_INT size
CS_INT *bytes_read,
CS_FLOAT timeout)

Arguments:

• fd: Open file descriptor to read from or write to.

• buf: Data buffer to read to or write from.

• size: Size of buffer.

• bytes_read: Actual bytes read.

• timeout: Number of seconds for read timeout. (Within Open Server, you can obtain granularity less than seconds). Valid values are: -1, 0, >0. If the timeout_seconds parameter value is -1, ASC_write blocks until the port is readable. This feature should not be used within the Open Server application since all files are supposed to be opened and set for nonblocking I/O. If timeout is set to 0, ASC_read returns immediately and mimics UNIX read().

Return values:

• 0: Success.

• -1: A UNIX error occurred.

• -2: ASC_read timed out.

• -3: Port hangup detected.

• -4: EOF detected.

• -5: Network Operational Error.

This function initializes newly allocated memory, copies the contents of the previously allocated memory, and frees previously allocated memory before returning a pointer to the reallocated memory segment.

See also ASC_free(), ASC_diag().

If this function is unable to reallocate previously allocated memory on the heap, this function issues a system event and terminates the process. If the size of the reallocated memory segment is specified as zero, the previously allocated memory is available and a null pointer returned.

The content of the previously allocated memory is preserved if the size of the reallocated memory segment is greater than the current size. If not, it is truncated.

Syntax:

VOIDPTR ASC_realloc(VOIDPTR ptr,

CS_INT size,
CS_INT cur_size)

Arguments:

• ptr: Pointer to previously allocated and used memory.

• size: The size, in bytes, of the reallocated memory segment.

• cur_size: The size, in bytes, of the currently allocated memory segment.

Return values:

• new_ptr: Void pointer to the re-allocated (possibly moved) memory segment.

• NULL: If requested memory size is zero bytes.

This function resets the file status to the previous file status flag value.

For more information on fcntl(), refer to UNIX documentation.

Syntax:

CS_RETCODE ASC_reset_file_status(CS_INT fd,

CS_INT oflags)

Arguments:

• fd: File descriptor value.

• oflags: Saved file status flag value.

Return values:

• CS_SUCCEED: Operation successful.

• CS_FAIL: Operation on the file descriptor failed.

This function performs a reverse string comparison. It is used in B Tree search functions to compare nodes in a more random manner to generate a more balanced B tree structure.

Syntax:

int ASC_rstrcmp(const char *buf1,

const char *buf2)

Arguments:

• buf1, buf2: Character pointers to the strings to be compared.

Return values:

• >0: First string is lexicographically greater than the second when compared in reverse.

• <0: Second string is lexicographically greater than the first when compared in reverse.

• 0: First string is lexicographically equal to the second.

This function converts the UNIX time in seconds to a database format record.

Syntax:

void ASC_sec_to_dBdts(time_t sec,

CS_DATETIME *dts)

Arguments:

• sec: UNIX time in seconds.

• dts: Pointer to datetime variable to return the converted time value in.

This function sets files to blocking mode, saving the current file status flag value. Blocking mode I/O must not be performed from within an Open Server, since it will block the whole server.

For more information on fcntl(), refer to UNIX documentation.

Syntax:

CS_RETCODE ASC_set_fd_blocking(CS_INT fd,

CS_INT *flags)

Arguments:

• fd: File descriptor value.

• flags: Integer pointer. Saves current file status flag value.

Return values:

• CS_SUCCEED: Operation successful.

• CS_FAIL:Operation on the file descriptor failed.

This function sets files to nonblocking mode, saving the current file status flag value.

For more information on fcntl(), refer to UNIX documentation.

Syntax:

CS_RETCODE ASC_set_fd_nonblocking(CS_INT fd,

CS_INT *flags)

Arguments:

• fd: File descriptor value.

• flags: Integer pointer to save current file status flag value.

Return values:

• CS_SUCCEED: Operation successful.

• CS_FAIL: Operation on the file descriptor failed

This function sets the _new_handler global variable to point to the new_exeption_hdl() callback function. The previous _new_handler value is not required, and is neither returned nor saved in a static variable.

Both Control API and Client API main() invoke this function when the ASAP server/client application is initialized. This eliminates the new exception handling that is specific to a platform or complier.

Syntax:

void ASC_set_new_handler(CS_BOOL diag_initialized)

Arguments:

• diag_initialized: Boolean variable. Specifies whether ASAP diagnostics and event management variables have been initialized or not. Uses either system calls or ASAP API calls to log messages and terminate the application.

This function provides a thread with a sleep function similar to the UNIX sleep() function.

See also ASC_wakeup().

If the application is an application server, this function puts the calling thread to sleep for the specified time interval. If the application is an application client, this function puts the entire client process to sleep for the specified time interval.

Syntax:

void ASC_sleep(time_t seconds)

Arguments:

• seconds: The sleep period, in seconds, before the application is woken up.

This function converts the string date time format to ASAP datetime. This function is used primarily to convert datetime strings from Oracle database results to ASAP datetime format.

Syntax:

ASC_str_to_dts(CS_CHAR * date_str, CS_DATETIME *dts)

Arguments:

• date_str: Pointer to datetime string in the following format: YYYYMMDD 24HH:MM:SS. For example, 19980111 10:04:00. This is the format which is returned from the Oracle Server as defined in the set_session database function at login.

• dts: Returned ASAP datetime.

This function walks the tree and performs an action at each node.

For more information, refer to the Action Function example on "Action function."

Syntax:

void ASC_walk_SBT(SBT *root,

void *data,
int(*action_fnt)(void **, void *, int, int))

Arguments:

• root: Pointer to the tree to walk.

• data: A void pointer that is passed as the second argument into the action function.

• action_fnt: Function that defines the action performed by the elements. Note that a pointer to a pointer is passed and, therefore, the data can change. Do not edit the key fields as the logical ordering is disrupted.

• First: A void pointer to the element to be processed.

• Second: A void pointer to the data argument passed to the ASC_walk_SBT function.

• Third: An integer defining the level that the element is on. The root element(s) are on level zero.

• Fourth: An integer defining the order in which the element was scanned. Possible values are:

  • INORDER – Scans all elements in node before proceeding to the next.

  • PREORDER – Scans the elements and then proceeds to the next node.

  • POSTORDER – Proceeds to the next node and scans the element on the way back.

Return values:

• 0: You need to continue to walk the rest of the tree.

• 1: You are finished with the walk.

This function provides a timeout using a nonblocking write. Write Timeout is achieved in UNIX code by setting alarm() before calling a write system call.

This function assumes that the file descriptor has not been set to nonblocking mode.

The alarm() call to time out the write call cannot be used since the Sleep Manager thread provided by ASAP Server API uses alarm() to implement sleep management. Instead, ASC_write() calls ASC_poll() to provide timeout.

This function declaration is the same as the UNIX write function, except for the additional parameter that specifies the timeout in seconds.

Until all bytes are written or ASC_poll times out, ASC_write loops the ASC_poll() call to check if the port is readable/writable or timed out, and then calls write.

This function invokes ASC_poll() to check if port is readable. It is not intended to be used to read from disk files.

Syntax:

CS_INT ASC_write(CS_INT fd,

const void *buf,
CS_INT size,
CS_INT *bytes_written,
CS_FLOAT timeout)

Arguments:

• fd: Open file descriptor to read from or write to.

• buf: Data buffer to read from or write to.

• size: Size of buffer.

• bytes_written: Actual number of bytes written.

• timeout: Number of seconds for write timeout. Within the Open Server, you can specify a granularity of less than a second. Valid values are: -1, 0, >0. If the timeout_seconds parameter is a value of -1, ASC_write blocks until the port is writable. This should not be used within the Open Server application since all files are supposed to be opened and set for nonblocking I/O. If timeout is set to 0, ASC_write returns immediately and mimics UNIX write().

Return values:

• 0: Okay.

• -1: A UNIX error occurred.

• -2: ASC_write timed out.

• -3: Port hangup detected.

• -5: Network Operational Error (host down, network down, and so on)

This function extracts name and value parts for the next message line beginning in the start position you specify in the input transaction buffer.

The message is in the format NAME=VALUE;\n and the buffer should look like: NAME=VALUE;\n[NAME=VALUE;\n]. Ensure that name and value buffers are large enough to hold the information.

Syntax:

int get_name_value(char *input_buf,

int start_pos,
int buf_len,
char *name,
char *value)

Arguments:

• input_buf: Character buffer containing the transaction.

• start_pos: Specifies start position to get current line. (Input)

• buf_len: Specifies length of input buffer. (Input)

• name: Variable to save the name as part of the message in line. (Output)

• value: Variable to save the value as part of the message in line. (Output)

Return values:

• int: Start position for next message line in the input buffer.

This function determines the difference between two times expressed in milliseconds.

Syntax:

MS_DIFF(start, end)

This function returns the current day of the year.

Syntax:

TODAY()     today()
int today(void)

Return values:

• Day of the year: Current day of the year.

Example:

int yday; yday = TODAY();

This structure informs the API which functions to call when certain results are returned. If you do not include a return result, the API uses the default processing to handle the data for the result set and continues processing. The default processing generally ignores the result row.

If you want to use the default processing for a return result type, do not include the result type in the table.

Syntax:

typedef struct {

CS_RETCODE (*handler)(CLIENT_PROC *cp, CS_VOID *data,
CS_INT res_type, CS_BOOL *not_done)
CS_INT res_type;

} CLIENT_HANDLER;

Members:

• handler: The handler function to call when a return result is matched. To indicate the end of the table, this field should be set to NULL.

• res_type: Return result type. Refer to the description for more information regarding result types.

This structure is used to define an RPC to invoke or define a registered procedure.

Syntax:

typedef struct{

CS_CHAR *rpcname;
CM_RPC_PARAM *paraminfo;
CS_INT numparam;
CS_RETCODE (*reghandler) (SRV_PROC *srvproc)

} CM_RPC;

Members:

• rpcname: Name of RPC or registered procedure.

• paraminfo: Pointer to the parameter structure. Set it to NULL if there is no parameter.

• numparam: Total number of parameters defined in this structure. Set to NULL if there is no parameter required, otherwise use the macro NUM_RPC_PARAM().

• reghandler: The handler function that is called when a registered procedure arrives.

This structure is used to define the parameter for RPCs and registered procedures. It is used to retrieve parameters when receiving a registered procedure or sending an RPC. The parameters defined in this structure should be in the correct order expected for sending and receiving. The first parameter is passed to the function as item 1.

Syntax:

typedef struct {
    CS_DATAFMT dfmt;
    CS_BYTE *datap;
    CS_INT datalen;
} CM_RPC_PARAM;

Arguments:

• dfmt: Data description structure defined by the header file which stores necessary format information for the parameter.

• datap: Pointer to the data as default parameter used to define a registered procedure or retrieved from incoming registered procedure.

• datalen: Specify the length of data pointed by the datap member. This is only used when setting up default data. Check srv_regparam for details.

This enumeration specifies the valid diagnostic levels of an application process using the diagnostic API functions.

The diagnostic levels are used with the ASC_diag() function and other diagnostic functions within the API.

If the diagnostic level of the process is higher or equal to the diagnostic level of the ASC_diag() function, then that diagnostic message is written to the diagnostic file.

The diagnostic levels are:

• PROG

• SANE

• LOW

• KERN

PROG provides the lowest level of detail of the diagnostics. The details become progressively greater for each level, with KERN being the most detailed.

The remaining levels are only used to provide backwards compatibility for ASAP, and are not available to be set.

Syntax:

typedef enum {

KERNEL_LEVEL,
LOW_LEVEL,
FUNCTION_LEVEL,
RPC_LEVEL,
CONTRACT_LEVEL,
SANITY_LEVEL,
PROGRAM_LEVEL,
FATAL_LEVEL

} DIAG_LEVEL;

Members:

• KERNEL_LEVEL: Used by the kernel to generate diagnostic messages. It is only to be used by the core libraries for very low-level debugging of core code. You can set the application diagnostic level to KERN.

• LOW_LEVEL: Used by the application to generate low-level diagnostic messages from any of its functions. Such messages enable the programmer to debug an application. Once debugged, the diagnostic level of the application should be changed to provide less detail. You can set the application diagnostic level to LOW.

• FUNCTION_LEVEL: Used by the application at the beginning and end of each function to track the operation of the application. Not generally used in the core application.

• RPC_LEVEL: Used by the application to produce RPC diagnostic messages.

• CONTRACT_LEVEL: Used to specify the start and end of a particular instance of a contract.

• SANITY_LEVEL: Used by the application for high-level diagnostics. This level of diagnostic messages provides user information about the processing of the system. It is used for low level diagnostic messages. A production application has its diagnostic level set at either PROG or SANE.

• PROGRAM_LEVEL: This is primarily used to generate error messages when the application is running in a production environment.

• FATAL_LEVEL: Used for fatal error conditions if the process is terminated. Only used if an error condition occurs within the application such that if the application continued, more errors would occur and compound the problem. For instance, if a function is missing from the database, then the application terminates for manual intervention.

This section lists the global variables defined by this server API:

• RealSrvName: Actual name of the application server as known to the network (that is, the name in the Interfaces file). To obtain this name from the application configuration file, use the logical application name ApplName as the configuration parameter.

• server_context: Global context for the application server.

• ASAP_high_availability: Boolean flag. Indicates whether or not High Availability mode is active.

• ASAP_IS_ALIVE_INTERVAL:Global polling interval for checking connections between the servers.

The server library interface provides the following thread management structures and functions:

• ASC_alarm()

• ASC_await_init_completion()

• ASC_lockmutex

• ASC_malarm()

• ASC_msleep()

• ASC_reg_init_func()

• ASC_spawn()

• ASC_unlockmutex

• background_process_init()

• BACKGROUND_PROCESS

The server library interface provides the following memory management structures and functions:

• ASC_blk_alloc

• ASC_blk_free

• ASC_blk_realloc()

This section outlines the steps involved to have the application server receiving registered procedures or remote procedure calls from client applications.

Structures and functions included in this category are:

• add_appl_rpc()

• add_registered_proc()

• add_rpc

• ASC_define_events()

• ASC_define_rpc()

• ASC_get_reg_param()

• ASC_get_rpc_param()

• ASC_handle_results

• REG_PROC

• RPC

• RPC_PARAM

• USEREVENT

This section includes functions and structures to help you handle language requests. Structures and functions included in this category are:

• add_lang_handler()

• ASC_convert_msg

• ASC_convert_msg_user

• ASC_createmsgq

• ASC_deletemsgq

• ASC_getmsgq

• ASC_imsg_types

• ASC_imsg_types_user

• ASC_load_msg_tbl

• ASC_putmsgq

• ASC_send_text()

• LANG_HANDLER

Client process connection pool functions create a pool of client connections to SQL servers. These functions help you manage the creation of pools of client connections for any thread to use within the application server.

The pools of connections assume that connections to the SQL server do not need to be checked periodically to determine whether the server is still running. Connections to other application servers are checked regularly because these servers may become unavailable. If this happens, all connections to that server are released. If communicating with another application server, an application server spawns a driver thread to manage the network connections and check the connection periodically.

Structures and functions included in this category are:

• ASC_cppalloc()

• ASC_cpdbpcreate

• ASC_cppfree()

• ASC_in_system()

• ASC_in_territory

• ASC_cpdbpdestroy

This section includes I/O functions you can incorporate within an application server. Structures and functions included in this category are:

• ASC_poll()

• ASC_poll_timer()

Structures and functions included in this category are:

• ASC_getpid()

• ASC_threadproc()

• ASC_sendinfo()

• ASC_thread_field_bool()

• ASC_thread_field_int()

• ASC_thread_field_str()

• ASC_srv_field_bool()

• ASC_srv_field_int()

• ASC_srv_field_str()

• ASC_lock_strtok()

• ASC_stack_trace()

• ASC_unlock_strtok()

This function adds an RPC to the application server, either as an RPC or a registered procedure depending on a configuration parameter.

See also add_rpc, ASC_define_rpc.

This function has been superseded by ASC_define_rpc().

Syntax:

CS_RETCODE add_appl_rpc(RPC *rpc)

Arguments:

• rpc: Pointer to the RPC definition structure.

Return values:

• CS_SUCCEED: Addition successful.

• CS_FAIL: Too many RPCs added to the server.

This function scans the current list of installed language handlers and installs a new language handler at the end of the list. If the maximum number (100) of language handlers has been exceeded, a system event is issued.

Syntax:

void add_lang_handler(LANG_HANDLER *hand)

Arguments:

• hand: Pointer to a language handler structure containing the language handler details.

Example:

static int run_lang_handler(SRV_PROC *srvproc, CS_CHAR *langptr, CS_INT langlen);
/* Language Handler Definition */
static LANG_HANDLER run_lang_def = {
    "run", "run", run_lang_handler
};
void init_function(void)
{
...
    add_lang_handler(&run_lang_def);
}
static int run_lang_handler(SRV_PROC *srvproc, CS_CHAR *langptr, CS_INT langlen)
{
    /* Process the language buffer */
    ...
    /* Complete the language request */
    srv_sendstatus(srvproc, 0);
    srv_senddone(srvproc, SRV_DONE_FINAL, 0, 0);
    return CS_SUCCEED;
}

This function adds the registered procedure specified by the rp argument to the application server.

The use of this function is no longer recommended. Instead, use the ASC_define_rpc() function.

Syntax:

CS_RETCODE add_registered_proc(REG_PROC *rp)

Arguments:

• rp: Pointer to the REG_PROC structure.

Return values:

• CS_SUCCEED: Addition successful.

• CS_FAIL: Too many RPCs added to the server.

This function adds a procedure to a server as a remote procedure. Use this function to add procedures that take optional parameters as registered procedures do not allow optional arguments.

Only use this function to define RPCs to the server. Such procedures take variable numbers of arguments. If the procedure takes a fixed number of non-null arguments, it should be defined as a registered procedure.

Syntax:

CS_RETCODE add_rpc(RPC *rpc)

Arguments:

• rpc: Pointer to the RPC structure.

Return values:

• CS_SUCCEED: Addition successful.

• CS_FAIL: Too many RPCs added to the server.

This function sets up an asynchronous alarm for a thread. The msg argument uniquely identifies the alarm and must point to a data segment where the first four bytes is the message operation. When the alarm expires, the message is sent to msgqid with the operation set to msg_operation. To cancel the alarm, set the seconds argument of this function to zero.

Any thread calling this function MUST be awaiting messages on a previously created message queue.

The thread message structure must have a long integer as the first field. This integer field is used as the message operation field, identifying the message type to the receiving thread. The first action of this function is to assign the msg pointer to the msg_operation value, thus setting the message operation for the alarm wakeup message. After this first message field, the message can have any format that the sending and receiving threads agree upon.

Syntax:

void ASC_alarm(time_t seconds, SRV_OBJID msgqid, int *msg, long msg_operation)

Arguments:

• seconds: Time, in seconds, after which the alarm is issued.

• msgqid: The thread message queue to which the thread message is to be sent. Note that the calling thread must have a dedicated thread message queue in order to receive the alarm notification.

• msg: An integer pointer to the previously allocated alarm message data area.

• msg_operation: The message operation used to identify an alarm message being received.

This function waits for the initialization process to complete before continuing to execute.

Syntax:

void ASC_await_init_completion(void)

This function returns a pointer to a memory block of a specified size (bytes). The memory is from a preallocated pool. ASC_BLK_ALLOC is called to interface with this function.

See also ASC_mem_alloc.

Each memory pool has a default number of blocks. This value is configurable in ASAP.cfg.

Syntax:

VOIDPTR ASC_blk_alloc(int line, char *file, CS_INT size, CS_CHAR *type_name)

Arguments:

• line: The line number of the function in the source file, “__LINE__".

• file: The file from which the function was called, “__FILE__".

• size: The number of bytes required.

• type_name: Name of type to be allocated.

This macro selects a block of memory from the appropriate memory pool that satisfies the size requirements of the structure specified by count * struct_name.

One block of memory is returned that is large enough to hold a number of instances of the structure. The number of instances is specified by count.

If required, you can change the number of blocks in each memory pool in ASAP.cfg.

Syntax:

(struct_name*) ASC_BLK_ALLOC (struct_name, struct_desc, count)

Example:

void function()
{

MY_STRUCTURE item1, item2;
MY_STRUCTURE *array;
array = ASC_BLK_ALLOC (MY_STRUCTURE, "MY_STRUCTURE", 1);
array[0] = item1;
array = ASC_BLK_REALLOC (array, MY_STRUCTURE, "MY_STRUCTURE", 2);
array[1] = item2;
ASC_BLK_FREE (array);

}

This macro returns the block of memory, specified by ptr, to its memory pool. The default number of memory blocks is configured in ASAP.cfg.

For an example of the use of this macro, refer to ASC_BLK_ALLOC.

Syntax:

void ASC_BLK_FREE (ptr)

This function returns a pointer to a new block of a specified size (bytes). The contents of the specified address are moved to the new block. ASC_BLK_REALLOC is called to interface with this function.

For more information on the default number of blocks assigned to memory pools, see "ASC_BLK_ALLOC."

Each memory pool has a default number of blocks. The ASC_BLOCK##_POOL value is configured in ASAP.cfg.

Syntax:

VOIDPTR ASC_blk_realloc(VOIDPTR addr, int line, char *file, CS_INT size, CS_CHAR *type_name)

Arguments:

• addr: The address of current allocation.

• line: The line number of the function in the source file, “__LINE__".

• file: The file from which the function was called, “__FILE__".

• size: Number of bytes required.

• type_name: Name of type to be allocated.

This macro selects a block of memory from the appropriate pool that will satisfy the size requirements of the structure specified by count * struct_name.

For an example of the use of this macro, refer to ASC_BLK_ALLOC.

Copies the contents of the previous block (specified by ptr) into the new block, and then returns the previous block to its pool.

One block of memory is returned that is large enough to hold a number of instances of the structure. The number of instances is specified by count.

The default number of memory blocks is configured in ASAP.cfg.

Syntax:

struct_name*) ASC_BLK_REALLOC (ptr, struct_name, struct_desc, count)

This function creates a CLIENT_PROC connection pool to the database server of the size you specify.

Syntax:

CLIENT_PROC_POOL ASC_cpdbpcreate(CS_CHAR *pool_name, CS_CHAR *srv_name, CS_CHAR *userid, CS_CHAR *password, CS_INT size, CP_CONNECT_TYPE cp_type)

Arguments:

• pool_name: Name of the client process pool.

• srv_name: Name of the server to establish a connection with.

• userid: User ID for security validation by the server.

• password: Password for security validation by the server.

• size: Number of client connection processes to be established.

• cp_type: Connection type. Valid values include:

  • OPEN_SERVER – Sybase Open Server Connection type.

  • ORACLE – Oracle Server RDBMS Connection type.

This function destroys the client process connection pool and frees all processes.

Syntax:

void ASC_cpdbpdestroy(CLIENT_PROC_POOL *cpp)

Arguments:

• cpp: Pointer to the client pool.

This function allocates a client process from the client process connection pool.

See also ASC_cppfree.

Syntax:

CLIENT_PROC *ASC_cppalloc(CLIENT_PROC_POOL *cpp)

Arguments:

• cpp: Pointer to the client process pool.

Return values:

• NULL: The function failed and the client process could not be allocated. This will only happen if the client process pool is invalid.

• CLIENT_PROC*: Pointer to the allocated client process.

This function frees an allocated client process and returns it to the original pool.

See also ASC_cppalloc.

Syntax:

void ASC_cppfree(CLIENT_PROC *cp)

Arguments:

• cp: Pointer to the client process structure.

This function creates an Open Server message queue. When a message queue is created, a mutex for that queue is also created. Therefore, the Open Server must be configured to allow the creation of enough mutexes.

See also ASC_deletemsgq, ASC_putmsgq and ASC_getmsgq.

Syntax:

CS_RETCODE ASC_createmsgq(CS_CHAR *mqname, 

CS_INT mqlen, 
SRV_OBJID *mqid)

Arguments:

• mqname: Pointer to the message queue name.

• mqlen: Length of the message queue name.

• mqid: Pointer to the message queue ID.

Return values:

• CS_SUCCEED: The message queue was created successfully.

• CS_FAIL: The creation of the message queue failed.

This function creates a mutex.

See also ASC_deletemutex, ASC_lockmutex, and ASC_unlockmutex.

Syntax:

CS_RETCODE ASC_createmutex(CS_CHAR *mutex_name, 

CS_INT mutex_namelen, 
SRV_OBJID *mutex_id)

Arguments:

• mutex_name: The name of the mutex.

• mutex_namelen: The length of the mutex name if not null terminated.

• mutex_id: The mutex ID returned during creation.

Return values:

• CS_SUCCEED: The mutex was created successfully.

• CS_FAIL: An error in the operation.

This function installs handlers for user-defined events.

Syntax:

CS_RETCODE ASC_define_events(USEREVENT *tbl)

Arguments:

• tbl: Table of user events to be installed into the application server.

Return values:

• CS_SUCCEED: The user events were successfully installed into the application server.

• CS_FAIL: The installation failed.

This function registers a procedure with the application server.

Syntax:

CS_RETCODE ASC_define_rpc(CM_RPC *reg_def)

Arguments:

• reg_def: Pointer to the RPC definition structure.

Return values:

• CS_SUCCEED: Addition successful.

• CS_FAIL: RPC could not be defined in the server.

This function deletes an Open Server message queue. The mutex created when the message queue was created will be removed.

See also ASC_createmsgq, ASC_putmsgq, and ASC_getmsgq.

Syntax:

CS_RETCODE ASC_deletemsgq(CS_CHAR *name, 

CS_INT length, 
SRV_OBJID id)

Arguments:

• name: Pointer to the name of the message queue.

• length: Length of the message queue.

• id: The ID of the message queue.

Return values:

• CS_SUCCEED: The message queue was deleted successfully.

• CS_FAIL: The deletion of the message queue failed.

This function deletes a mutex.

See also ASC_createmutex, ASC_lockmutex, and ASC_unlockmutex.

Syntax:

CS_RETCODE ASC_deletemutex(CS_CHAR *mutex_name, 

CS_INT mutex_namelen, 
SRV_OBJID mutex_id)

Arguments:

• mutex_name: The name of the mutex.

• mutex_namelen: The length of the mutex name if not null terminated.

• mutex_id: The mutex ID specified during deletion.

Return values:

• CS_SUCCEED: The mutex was deleted successfully.

• CS_FAIL: An error occurred during the operation.

This function determines the parameters for a registered procedure.

Syntax:

CS_RETCODE ASC_get_reg_param(SRV_PROC *srvproc, CM_RPC *reg_def, ...)

Arguments:

• srvproc: Pointer to the current thread structure.

• reg_def: Pointer to the registered procedure definition.

• ...: Variable list of data value pointers.

Return values:

• CS_SUCCEED: Addition successful.

• CS_FAIL: The determination of the parameters on the registered procedure failed.

This function retrieves a thread message.

See also ASC_createmsgq, ASC_putmsgq and ASC_deletemsgq.

Syntax:

CS_RETCODE ASC_getmsgq(SRV_OBJID msgqid, 

CS_VOID **msg, 
CS_INT flags, 
CS_INT *info)

Arguments:

• msgqid: Name of the message queue.

• msg: Indirect pointer to the thread message.

• flags: Informational flag – Populated upon failure.

• info: Information – Populated upon failure.

Return values:

• CS_SUCCEED: The message was received successfully.

• CS_FAIL: The message was not received.

This function gets the server process ID for the thread associated with the current server process.

Syntax:

CS_INT ASC_getpid(SRV_PROC *srvproc)

Arguments:

• CS_INT: Open Server process ID for the server process you specified.

• srvproc: The Open Server process handle.

Return values:

• SRV_PROC*: Pointer to current server process.

• CS_INT: Open Server process ID for the server process you specified.

Retrieves a secure data entry.

Syntax:

CS_RETCODE ASC_get_securedata(char *name, 

char*value);

Arguments:

• name: Used as key to retrieve secure data entry.

• value: Encrypted password field of the secure data entry.

Once a command has been sent to the SQL Server, this function processes the results and passes them back to the Open Server client.

Syntax:

CS_RETCODE ASC_handle_results(CLIENT_PROC *rmtproc, 

SRV_PROC *srvproc, 
CS_INT *last_row_cnt, 
CS_INT *tot_row_cnt)

Arguments:

• rmtproc: The Open Client Library handle to the remote DBMS.

• srvproc: The Open Server process handle to use to send results to the client.

• last_row_cnt: Pointer to the number of rows transmitted to the client in the last set of results in the command batch. This can be used by the calling function to determine whether any such rows were returned to the client and to set the row count in the final srv_senddone() statement. If not required, set this field to NULL.

• tot_row_cnt: Pointer to the total number of rows transmitted to the client. This determines whether any command result rows were transmitted to the client. If not required, set this field to NULL.

Return values:

• CS_SUCCEED: Successfully returned data rows (if any).

• CS_FAIL: Error.

This function checks whether or not the specified component is defined in the specified territory and system. This function is related to high-availability installations.

Syntax:

CS_RETCODE ASC_in_system(CS_CHAR *territory, 

CS_CHAR *system, 
CS_CHAR *component)

Arguments:

• territory: Name of the ASAP territory to check.

• system: Name of the ASAP system to check within the territory.

• component: Name of the component to check in the system.

Return values:

• CS_SUCCEED: The component is defined for the ASAP territory and system.

• CS_FAIL: The component is not defined for the ASAP territory and system.

This function checks if the specified component is defined in the specified territory.

Syntax:

CS_RETCODE ASC_in_territory(CS_CHAR *territory, 

CS_CHAR *component)

Arguments:

• territory: Name of the ASAP territory to check.

• component: Name of the component to check in the system.

Return values:

• CS_SUCCEED: The component is defined for the ASAP territory.

• CS_FAIL: The component is not defined for the ASAP territory.

This function locks mutexes.

See also ASC_unlockmutex.

Syntax:

CS_RETCODE ASC_lockmutex(SRV_OBJID mutex_id, 

CS_INT waitflag, 
CS_INT *infop)

Arguments:

• mutex_id: The mutex ID returned during locking.

• waitflag: Specifies whether the thread requesting the lock of the mutex should wait or return if the mutex cannot be locked.

• infop: A pointer to a CS_INT. Refer to the appropriate Sybase documentation for appropriate values.

Return values:

• CS_SUCCEED: The mutex was locked successfully.

• CS_FAIL: An error in the operation.

Since the UNIX function strtok() maintains a global or static variable of its current position within the string, it is not multi-thread-safe. ASC_lock_strtok is used in conjunction with strtok() in a multi-threaded environment. After you have finished using strtok(), ASC_unlock_strtok() must be called to free the associated mutex.

Syntax:

void ASC_lock_strtok(void)

This function sets up an asynchronous alarm for a thread. It provides the same functionality as ASC_alarm but is used to provide timing of less than one second.

See also "ASC_alarm."

Syntax:

void ASC_malarm(CS_FLOAT  timeout, 

SRV_OBJID msgqid, 
int *msg, 
long msg_operation)

Arguments:

• timeout: Time, in milliseconds, after which the alarm goes off.

• msgqid: The thread message queue to which to send the thread message. Note that the calling thread must have a dedicated thread-message queue in order to receive the alarm notification.

• msg: An integer pointer to the previously allocated alarm message data area.

• msg_operation: The message operation used to identify an alarm message being received.

This function allocates a fixed size block from the memory pool.

See also ASC_mem_free, ASC's libcontrol RPC call “mem_usage" for usage statistics, and ASC_mem_create libcontrol API call to create a memory pool.

Upon startup, a pool of memory is created. The pool can hold several records of information. If the pool is not large enough, it is automatically resized to accommodate the new records. When ASC_mem_alloc is called, a record is assigned as in_use and returned as a VOIDPTR (a generic C pointer which can be defined as any type).

The ASAP Memory Manager controls the constant allocation, deallocation, and reallocation of memory. These procedures are expensive in terms of CPU usage. The pool is allocated only once. All the ASC_mem_allocs and ASC_mem_free functions that are called, simply update the in_use flag of each memory record.

Syntax:

VOIDPTR ASC_mem_alloc(int line, char *file, 

ASC_MEM_POOL *pool)

Arguments:

• line: The line number of the function in the source file, "__LINE__".

• file: The file from which the function was called, "__FILE__".

• ASC_MEM_POOL *pool: The name of the memory pool.

This function frees a fixed sized block and returns it to the memory pool.

See also ASC_mem_alloc, ASC's libcontrol RPC call “mem_usage" for usage statistics, and ASC_mem_create libcontrol API call to create a memory pool.

When the ASC_mem_alloc pointer allocated is no longer needed, ASC_mem_free automatically returns it to the correct pool.

The ASAP Memory Manager controls the constant allocation, deallocation, and reallocation of memory. These procedures are expensive in terms of CPU usage. The pool is allocated only once. All the ASC_mem_allocs and ASC_mem_free functions that are called update the in_use flag of each memory record.

Syntax:

void ASC_mem_free(int line, 

char *file, 
VOIDPTR p)

Arguments:

• line: The line number of the function in the source file, "__LINE__".

• file: The file from which the function was called, "__FILE__".

• VOIDPTR: A generic C pointer which can be defined as any type.

This function allows a thread to sleep for the time, in seconds, that you specify. If you want to set the time in milliseconds, specify the fractional part of a second.

See also ASC_sleep.

Syntax:

void ASC_msleep(CS_FLOAT seconds)

Arguments:

• seconds: Number of seconds to send the thread into sleep state.

This function is the Application server poller that provides timeout. The Open Server Poller function srv_poll() in the blocking mode (SRV_M_WAIT) does not provide a timeout. The alarm() call cannot be used to time out the srv_poll() call since the Sleep Manager thread provided by ASAP Server API uses the alarm() to implement sleep management. ASC_poll() provides srv_poll() functionality allowing for timeout like UNIX I/O multiplexing call poll().

This function declaration is the same as for srv_poll() except for the additional parameter that specifies the timeout in seconds. There is also an additional return value, -2, which indicates that srv_poll() timed out.

ASC_poll() implements the timeout by creating a socketpair and sending the write endpoint of the socketpair in a timeout request message to the sleep manager. The read endpoint of the socketpair is added to the list of ports to be watched for. If an event occurs in any of the ports, the sleep manager is sent a timer cancellation, and the return value from the srv_poll() is returned. Otherwise, if the timeout message from sleep manager is received on the read endpoint of the socketpair connection, it returns a value of -2 to indicate timeout.

All ASAP Application servers should call ASC_poll() instead of directly calling srv_poll().

Setting a timeout of 0 is equivalent to calling srv_poll() with wait-flag set to SRV_M_NOWAIT.

Setting a timeout of -1 is equivalent to calling srv_poll() with wait-flag set to SRV_M_WAIT.

Setting a timeout > 0 provides poll-like functionality.

Syntax:

CS_INT ASC_poll(SRV_POLLFD *fdsp, 

CS_INT nfds, 
CS_FLOAT timeout)

Arguments:

• fdsp: Pointer to an array of SRV_POLLFD structures with one element for each open file descriptor of interest.

• nfds: Number of elements in the *fdsp array.

• timeout: Number of seconds for srv_poll timeout. Open servers do not support granularity of less than seconds. Valid values are: -1, 0, > 0. If the timeout_seconds parameter is a value of -1, ASC_poll() does not return until at least one specified event has occurred. If the value of the parameter is 0, ASC_poll() does not wait for an event to occur but returns immediately, even if no specified event has occurred. This is consistent with UNIX poll behavior.

Return values:

• n: The number of file descriptions.

• 0: No file descriptors are ready, or ASC_poll timed out. This is consistent with UNIX poll behavior.

• -1: An error occurred.

This function sets up an asynchronous alarm to provide timeout while polling for data for a thread. The msg argument uniquely identifies the timer and must point to a data segment where the first (4 bytes) is the message operation. When the timer expires, the message integer pointer is written to the socket sock_fid.

See also "ASC_poll."

To cancel the timer, set the timeout argument to zero (0.0) seconds.

Any thread calling this function MUST be polling for messages on the read end of the socketpair connection.

The format and contents of the message may have any format because the msg pointer is written to the sock_fid. The caller must be responsible for handling if the message pointed to has been deallocated.

Syntax:

void ASC_poll_timer(CS_FLOAT timeout, 

int sock_fid, 
int *msg)

Arguments:

• timeout: Time, in seconds, specified as the floating point value after which the timer expires. The granularity is to the millisecond.

• sock_fid: Write end of the socketpair connection over which the timer notification is sent. The calling thread must create a socketpair, allocate one end as the write end and the other as the read end, send it to sleep manager as part of ASC_poll_timer(), and poll for messages on the read end of the socketpair.

• msg: An integer pointer to the previously allocated timer message data area. The caller is responsible for populating the data area with information needed on timeout notification from the sleep manager and deallocating the data area.

This function adds a thread message to a particular message queue.

See also ASC_createmsgq, ASC_getmsgq, and ASC_deletemsgq.

Syntax:

CS_RETCODE ASC_putmsgq(SRV_OBJID mqid, 

CS_VOID *msgp, 
CS_INT flags)

Arguments:

• mqid: Name of the message queue.

• msgp: Pointer to the thread message.

• flags: Message processing flags.

Return values:

• CS_SUCCEED: The message was sent successfully.

• CS_FAIL: An error occurred during message send.

This function registers an initialization function within the application server with a priority specified by its first argument. Such functions execute in serial order by priority by the initialization thread within the server API. While this thread executes these initialization functions, an initialization mutex is locked, preventing other threads from starting up until all the initialization functions have finished.

Such initialization functions can perform network I/O activities such as loading static tables from the database, etc. This type of network activity cannot be performed from within the SRV_START handler. Therefore, it is necessary to spawn a separate initialization thread to execute these tasks.

The initialization thread does not begin executing until the SRV_START event handler has finished, that is, appl_initialize() has returned, allowing the application to register its initialization functions before the initialization thread begins.

This function must be called from within the SRV_START handler function, either in the API or in the appl_initialize() application-supplied function.

Syntax:

void ASC_reg_init_func(int level, 

char *desc, 
CS_RETCODE (*init_func)(void))

Arguments:

• level: Priority of the initialization function. 0 to 10 is reserved for the API. The application server code can use > 10.

• desc: Description of the initialization function.

• init_func: Function pointer to initialization function.

This function sends a language command, text buffer, and if required, the contents of the specified file to an application server. The command that is placed on the first line of the text to be sent determines which language handler the destination server invokes.

See also add_lang_handler().

If the filename is set, the command, the contents of the file, and the buffer are transmitted in that order. If the filename is NULL, the command and buffer are transmitted.

This function also determines whether or not there is a thread already spawned to act as a language driver thread to the specified application server. If a thread exists, it sends a synchronous thread message to that thread, which then transmits the text buffer and returns a status value to the calling function.

If no such thread currently exists, a language driver thread is spawned within the server process to establish and maintain a network connection to the destination application server. From this point on, all text transmission requests are directed to this thread.

It is important that you specify the correct command in this function so that the destination application server executes the correct language handler.

Syntax:

CS_RETCODE ASC_send_text(char *server, 

char *command, 
char *filename, 
char *buf)

Arguments:

• server: The logical name for the application server to where the language request is to be transmitted.

• command:Character pointer to a command that is placed in the first line of the transmitted text and is used by the receiving application server to determine the relevant language handler to execute.

• filename: The location for the file that is to be transmitted. If you are not transmitting a file, set this to NULL.

• buf: Character buffer to be transmitted. If you specify a filename, this buffer is appended to the file contents in the text. If you are not transmitting a buffer, set this to NULL.

Return values:

• CS_FAIL: Unable to open a network connection to the destination server. The invocation of dbsqlexec() failed.

• CS_SUCCEED: The text was successfully transmitted.

This function sends an information message to the client.

Syntax:

CS_RETCODE ASC_sendinfo(SRV_PROC *sp, 

CS_INT msgno, 
CS_CHAR *msg)

Arguments:

• sp: Pointer to the internal thread control structure.

• msgno: Message number being sent.

• msg: Message text to send.

Return values:

• CS_SUCCEED: Message was sent to client.

• CS_FAIL: Error occurred sending message.

Updates or adds user-defined, secure data.

Syntax:

CS_RETCODE ASC_set_securedata(char *name, 

char*value, 
char *desc);

Arguments:

• name: Key to retrieve the secure data entry.

• value: Value (password) of the secure data entry.

• desc: Description of the secure data entry.

This function sets the server process data segment and then spawns a generic Open Server thread that sets up the application thread.

Using this function, you can pass a message queue name to be created by this function. You can also specify a main function, an exit function, and request that a database connection be established for the spawned thread.

You can access the structure created within the API to manage this spawned thread using the following in-line functions:

• ASC_SRV_DBPROC – If you request that a DBPROC be created, this macro points to the DBPROCESS structure allocated by the API for use by this thread.

• ASC_SRV_MSGQID – If you request that a message queue be created for this thread, the message queue ID of the message queue created by the API.

• ASC_SRV_DATA – If the dataseg_size is not zero, this serves as a pointer to the data segment that is allocated by the API for use by the spawned thread. The thread, or any function called by it, may reference this data segment at any time using this macro.

• ASC_SRV_STARTUP – The data segment passed as an argument to the spawned function. This is the start_seg passed to ASC_spawn().

Syntax:

CS_RETCODE ASC_spawn(CS_CHAR *name, 

int (*main_fn)(VOIDPTR data_seg), 
VOIDPTR start_seg, 
CS_INT dataseg_size, 
CS_CHAR *msgname, 
CS_BOOL dbproc_required, 
CS_RETCODE (*exit_handler)(SRV_PROC *srvproc))

Arguments:

• name: Name of the server process.

• main_fn: Pointer to the main function of the application thread. When this function terminates, the server process terminates.

• start_seg: Pointer to the startup data segment of the server process.

• dataseg_size: Size of local data segment required by the application.

• msgqname: The message queue that the server process will read. If no message queue is required, set this to NULL.

• dbproc_required: Identifies whether or not the server process requires an application database process.

• exit_handler: Pointer to the function that is called when the server process terminates. If no server process is required, set this field to NULL.

Return values:

• CS_SUCCEED: The spawning of the server process was successful.

• CS_FAIL: No server processes were available.

This function calls srv_props to return a field in the server structure:

• ASC_srv_field_str – Retrieves strings

• ASC_srv_field_int – Retrieves integers

• ASC_srv_field_bool – Retrieves boolean

Syntax:

CS_BOOL ASC_srv_field_bool(CS_INT property)

Arguments:

• property: The property to retrieve.

Return values:

• CS_BOOL: Boolean value for the server property.

This function calls srv_props to retrieve a field in the server structure:

• ASC_srv_field_str – Retrieves strings

• ASC_srv_field_int – Retrieves integers

• ASC_srv_field_bool – retrieves boolean

Syntax:

CS_INT ASC_srv_field_int(CS_INT property)

Arguments:

• property: The property to retrieve.

Return values:

• CS_INT: Integer value for the server property.

This function calls srv_props to retrieve a field in the server structure:

• ASC_srv_field_str – retrieves strings

• ASC_srv_field_int – Retrieves integers

• ASC_srv_field_bool – Retrieves boolean

Syntax:

CS_VOID ASC_srv_field_str(CS_INT property,

CS_CHAR *buf, 
CS_INT size)

Arguments:

• property: The property to retrieve.

• buf: Pointer to the destination buffer for string properties.

• size: Maximum size of the destination buffer.

This is a wrap function around srv_sleep function. ASC adds an extra feature: if sleep is interrupted by a signal of the same variety, the thread continues to sleep.

The thread sleeps until srv_wakeup is called on the same event.

For more information on the srv_sleep function, refer to Sybase documentation.

Syntax:

CS_RETCODE ASC_srv_sleep(CS_VOID *sleepeventp, 

CS_CHAR *sleeplabelp, 
CS_INT sleepflags, 
CS_INT *infop, 
CS_VOID *reserved1, 
CS_VOID *reserved2)

Arguments:

• sleepeventp: A generic void pointer that srv_wakeup uses to wake the thread or threads. The pointer should be unique for the operating system event that the threads are sleeping on. For example, if a message is passed to another thread, the sending thread could sleep until the message is processed. The pointer to the message would be a useful sleep event that the receiving thread could pass to srv_wakeup to wake the sender.

• sleeplabelp: A pointer to a null terminated character string that identifies the event that the thread is sleeping on. This is useful for determining why a thread is sleeping. An application can display this information using the Open Server system registered procedure sp_ps.

• reserved1: A platform-dependent handle to a mutex. This argument is ignored on non-preemptive platforms. Set it to (CS_VOID*)0 on non-preemptive platforms.

• reserved2: This parameter is not currently used. Set it to 0.

• sleepflags: The value of this flag determines the manner in which the thread wakes up.

• infop: A pointer to a CS_INT.

For more information on the appropriate values for sleepflags and infop, refer to the Sybase documentation.

This function prints the stack trace to the server's diagnostic logfile. It calls the Open Server srv_dbg_stack() function to perform this operation.

See also ASC_diag(), ASC_hex_dump(), ASC_rpc_dump().

This function is supported only on platforms where Sybase supports debug capability (this is governed by the SRV_C_DEBUG capability). It is not supported under AIX.

Syntax:

void ASC_stack_trace(DIAG_LEVEL level, 

char *type, 
int line, 
char *file)

Arguments:

• level: The diagnostic level for the function call. See ASC_diag() for more information.

• type: Brief description of the circumstances for the function call. It helps to identify such entries in the server's logfile.

• line: The line in the source file at which the function was called.

• file: The source file from which this function was called.

This function calls srv_thread_props to retrieve a field in the thread structure:

• ASC_thread_field_str – Retrieves strings

• ASC_thread_field_int – Retrieves integers

• ASC_thread_field_bool – Retrieves boolean

Syntax:

CS_BOOL ASC_thread_field_bool(SRV_PROC *sp, 

CS_INT property)

Arguments:

• sp: Current thread structure.

• property: The property to retrieve.

Return values:

• CS_BOOL: Boolean value for the thread property.

This function calls srv_thread_props to retrieve a field in the thread structure:

• ASC_thread_field_str – Retrieves strings

• ASC_thread_field_int – Retrieves integers

• ASC_thread_field_bool – Retrieves boolean

Syntax:

CS_INT ASC_thread_field_int(SRV_PROC *sp, 

CS_INT property)

Arguments:

• sp: Current thread structure.

• property: The property to retrieve.

Return values:

• CS_INT: Integer value for the thread property.

This function calls srv_thread_props to retrieve a field in the thread structure:

• ASC_thread_field_str – Retrieves strings

• ASC_thread_field_int – Retrieves integers

• ASC_thread_field_bool – Retrieves boolean

Syntax:

CS_VOID ASC_thread_field_str(SRV_PROC *sp, 

CS_INT property, 
CS_CHAR *buf, 
CS_INT size)

Arguments:

• sp: Current thread structure.

• property: The property to retrieve.

• buf: Pointer to the destination buffer for string properties.

• size: Maximum size of the destination buffer.

This function gets the pointer to the server process associated with the current thread.

Syntax:

SRV_PROC *ASC_threadproc(void)

Return values:

• SRV_PROC*: Pointer to current server process.

This function unlocks mutexes.

See also ASC_lockmutex.

Syntax:

CS_RETCODE ASC_lockmutex(SRV_OBJID mutex_id)

Arguments:

• mutex_id: The mutex ID.

Return values:

• CS_SUCCEED: The mutex was unlocked successfully.

• CS_FAIL: An error occurred.

Because the UNIX function strtok() maintains a global or static variable of its current position within the string, it is not multi-thread-safe. ASC_lock_strtok is used in conjunction with strtok() in a multithreaded environment. When finished using strtok(), ASC_unlock_strtok() must be called to free the associated mutex.

Syntax:

void ASC_unlock_strtok(void)

This function initializes the background processes in the server.

Syntax:

CS_RETCODE background_process_init (BACKGROUND_PROCESS *tbl)

Arguments:

• tbl: Table listing the background processes to be started in the server.

Return values:

• CS_SUCCEED: The background processes started successfully.

• CS_FAIL: An error occurred and the processes could not start.

This structure defines the background or service thread spawned by the application server.

Refer to ASC_spawn() for further details about spawning service threads.

Syntax:

typedef struct {

char *qname;
SRV_OBJID *msgqxp;
int (*start)(void *data_seg);
void *data_seg;
BACKGROUND_PROCESS;

Members:

• qname: Name of the message queue to be created for this service thread.

• msgqxp: Pointer to the location where the message queue ID is to be placed.

• start: Function pointer to the main thread function.

• data_seg: Pointer to a data segment to be made available to the service thread.

This structure describes a language event handler.

Syntax:

typedef struct {

char command[LANG_HAND_COMMAND_L+1];
char usage[LANG_HAND_USAGE_L+1];
int (*handler)(SRV_PROC *srvproc, CS_CHAR *langptr,
CS_INT langlen);
LANG_HANDLER;

Members:

• command: The command associated with the language request. This will be the first line of the language text buffer that is passed to the application server.

• usage: The usage of language handler. This usage string is returned to the user in the lang_list RPC.

• handler: The function to call to handle this language request. The function syntax is the language handler syntax.

This data type has been superseded by the CM_RPC data type.

This data type is a registered procedure application definition.

Syntax:

typedef struct {

char *procname;
CS_RETCODE (*handler)(SRV_PROC *srvproc);
REG_PROC_PARAM *param_tbl;
REG_PROC;

Members:

• proname: Name of the registered procedure being defined.

• handler: RPC handler to process the registered procedure when it is executed.

• param_tbl: Register procedure parameter table.

Any new code for registered procedures should use the CM_RPC data type instead of this datatype. RPCs continue to use this data type.

This structure defines an RPC that is accepted by the server.

The function add_appl_rpc() is used to add the RPC to the list of RPCs being handled by the server.

Syntax:

typedef struct {

CS_CHAR *rpcname;
CS_CHAR *rpcusage;
RPC_PARAM *rpcparams;
CS_RETCODE (*rpchandler)(SRV_PROC *srvproc);
short min_params;
short max_params;
RPC;

Members:

• rpcname: The name to be used by clients when invoking the RPC (for example, exec SERVER...rpcname).

• rpcusage: The usage message that is sent to the user if there is a parameter mismatch.

• rpcparams: Parameters necessary to invoke the RPC. Set this to NULL if no parameters are required to invoke the RPC.

  The “rpcparams" field uses the “RPC_PARAM" datatype to specify the parameters used by the RPC.

• rpchandler: Pointer to a function to be called when the RPC is received by the library to handle the request. The function will have to accept a pointer to an SRV_PROC structure which contains information describing the server process.

• min_params: The minimum number of parameters required by the RPC before it is executed.

• max_params: The maximum number of parameters that can be accepted by the RPC before it is executed.

  The “min_params" and “max_params" fields are determined at run-time by the API when it scans the parameter table.

This structure defines the parameters for an RPC.

When an RPC is created using the datatype “RPC", you can specify an optional table of RPC parameters. This optional table contains a list of this datatype. Specify the end of the table by setting the paramname member to END_PARAM_TABLE.

Any new code should use the CM_RPC_PARAM data type instead of this datatype.

For more information, refer to datatype “RPC".

This structure is used to defined tables and should not be used as a general purpose data structure.

Syntax:

typedef struct {

char *paramname;
CS_BOOL null_allowed;
CS_BOOL optional;
int paramtype1;
int paramtype2;
int paramtype3;
RPC_PARAM;

Members:

• paramname: Parameter name in the form @name. To mark the end of table, set this parameter to END_PARAM_TABLE.

• null_allowed: A boolean field. Specifies whether the parameter allows null values.

• optional: A boolean field. Specifies whether or not the parameter can be omitted when the RPC is called. In this case, the processing function for the RPC is generating a default value.

• paramtype<n>: These fields specify different parameter types (maximum of three) that are valid for the parameter. The types that can be specified, including CS_CHAR_TYPE, CS_SMALLINT_TYPE, CS_INT_TYPE, etc.

This structure defines user events and the appropriate event handler. To define events, you need to define a table of this structure. To mark the end of the table, set the event field to NULL. The function ASC_define_events() is used to define user events to be handled by the server.

Syntax:

typedef struct {

int *event;
char *name;
CS_RETCODE (*event_handler)(SRV_PROC *srvproc);
USEREVENT;

Members:

• event: Pointer to the integer that is used to identify the user-defined event in the server. To mark the end of the table, set this field to NULL.

• name: The name of the event. This is useful for diagnostics and logs to show the current server event by name.

• event_handler: Pointer to the function that is called to handle the event when it occurs in the server.

This API function allows the client application to perform application-specific cleanup during the termination of the application.

See also appl_initialize() in the Common Interface API.

Syntax:

void appl_cleanup(void)

This function allocates and initializes an Interpreter data segment and sets it up to be used by an application that is not the command processor.

Syntax:

CMD_PROC_DATA *ASC_alloc_Interpreter(CS_CHAR *host_clli, 

CMD_PROC_MSG *msg, 
PORT_BIND_ST *port)

Arguments:

• host_clli: Determines the technology and software version.

• msg: Pointer to the command processor message. Can be null.

• port: Pointer to the Port Bind structure. Can be null.

Return values:

• CMD_PROC_DATA*: Pointer to the Interpreter data segment.

• NULL: An error occurred.

This function deletes the Interpreter variable you specify.

This is an inline function.

Syntax:

CS_RETCODE ASC_delete_int_var(CMD_PROC_DATA *data, 

char *label)

Arguments:

• data: Pointer to the Interpreter data segment.

• label: Interpreter variable label.

This function releases the memory associated with the Interpreter data segment.

Syntax:

void ASC_free_Interpreter(CMD_PROC_DATA *data)

Arguments:

• data: Interpreter data segment.

This function gets the device session information structure from the Interpreter.

This is an inline function.

See also ASC_set_dev_sess_data.

Syntax:

VOIDPTR ASC_get_dev_sess_data(COMM_DATA_ST *comm_data)

Arguments:

• comm_data: Pointer to the communication data structure within the Interpreter data segment.

Return values:

• dev_sess_data: Pointer to the device-specific information data structure.

This function retrieves the application data segment for the Interpreter.

This is an inline function.

Syntax:

VOIDPTR ASC_get_int_appl_data(CMD_PROC_DATA *data)

Arguments:

• data: Pointer to the Interpreter data segment.

Return values:

• VOIDPTR: Application data segment in use for the Interpreter.

This function retrieves the value for the Interpreter variable you specify.

This is an inline function.

Syntax:

CS_RETCODE ASC_get_int_var(CMD_PROC_DATA *data, 

char *label, 
char *value)

Arguments:

• data: Pointer to the Interpreter data segment.

• label: Interpreter variable label.

• value: Variable to save the value in.

Return values:

• CS_SUCCEED: Interpreter variable retrieval was successful.

• CS_FAIL: The retrieval failed.

This function initializes the Interpreter subsystem within a server. This initialization includes starting the cache manager, initializing the regular expression system, initializing the database process pool, etc.

The Interpreter can only be initialized once per process. Subsequent calls to ASC_init_Interpreter() are ignored.

Syntax:

void ASC_init_Interpreter(CS_CHAR *debug_host, 

DEBUG_CONFIGURATION_ST *dbg_cfg)

Arguments:

• debug_host: String that specifies the host CLLI that is used for debugging. It is currently not required.

• dbg_cfg: Field that specifies the debug configuration structure for the server. For servers that use an Interpreter other than an NEP, it is set to NULL.

This function sets up the appropriate data fields in the Interpreter data segment and calls the main Interpreter function to execute the State Table.

Syntax:

CS_RETCODE ASC_Interpreter(CMD_PROC_DATA *data, 

CS_CHAR *asdl_cmd, 
CS_BOOL auto_free) 

Arguments:

• data: Command processor data segment.

• asdl_cmd: ASDL command to be executed. The ASDL command is directly related to technology and software load, and this determines the State Table (as defined in tbl_nep_asdl_prog).

• auto_free: Boolean flag. Indicates if the Interpreter parameters are automatically made available upon completing the ASDL command.

Return values:

• CS_SUCCEED: State Table execution for the ASDL command was successful.

• CS_FAIL: State Table execution failed for the ASDL command.

This function sets the device session information structure for the Interpreter.

This is an inline function.

See also ASC_get_dev_sess_data.

Syntax:

void ASC_set_dev_sess_data (CMD_PROC_DATA *data, 

VOIDPTR *dev_sess_data)

Arguments:

• data: Pointer to the Interpreter data segment.

• dev_sess_data: Void pointer to a device-specific information structure.

This function sets the application data segment for the Interpreter.

This is an inline function.

Syntax:

void ASC_set_int_appl_data(CMD_PROC_DATA *data, 

VOIDPTR *appl_seg)

Arguments:

• data: Pointer to the Interpreter data segment.

• appl_seg: Pointer to a user-defined application data segment.

This function saves the Interpreter variable in the Interpreter application data segment.

Syntax:

CS_RETCODE ASC_store_int_var(CMD_PROC_DATA *data, 

char *label, 
char *value)

Arguments:

• data: Pointer to the Interpreter data segment.

• label: Interpreter variable label.

• value: Variable to save the value in.

Return values:

• CS_SUCCEED: The variable was saved in the Interpreter application data segment successfully.

• CS_FAIL: The save failed.

This function deletes a variable in the Interpreter data segment.

Syntax:

CS_RETCODE CMD_delete_var(CMD_PROC_DATA *data, 

char *label)

Arguments:

• data: Pointer to the Interpreter data segment.

• label: Interpreter variable label.

Return values:

• CS_SUCCEED: The variable was deleted successfully in the Interpreter data segment.

• CS_FAIL: The deletion failed.

This function copies the current action string into the buffer you specify and performs variable substitution.

Syntax:

CS_RETCODE CMD_expand_action_string(CMD_PROC_DATA *data, 

char *buf)

Arguments:

• data: Pointer to the local data segment for the command processor.

• buf: Pointer to the buffer that holds the expanded action string.

Return values:

• CS_SUCCEED: Successfully expanded the action string to the specified buffer.

• CS_FAIL: Could not expand the action string.

This function releases the memory for a specified assignment buffer that has been allocated using the CMD_get_assignment function.

Syntax:

void CMD_free_assignment(CMD_ASSIGNMENT_BUF *buf)

Arguments:

• buf: Pointer to the assignment buffer to be freed.

This function releases the memory for an assignment buffer that has been allocated using the CMD_get_bvar_assignment function.

See also CMD_get_bvar_assignment.

Syntax:

void CMD_free_bvar_assignment(CMD_BVAR_ASSIGNMENT_BUF *buf)

Arguments:

• buf: Pointer to the assignment buffer to be freed.

This function frees the database process.

Syntax:

void CMD_free_dbproc(DBPROCESS *dbproc)

Arguments:

• dbproc: Pointer to the DBPROCESS.

This function allocates an assignment buffer, parses the current action string, and stores the results in the buffer of a linked list. The primary difference between this function and the CMD_parse_assignment is that, with this function, the number of arguments is unlimited. If an error is detected, NULL is returned.

Variable substitution is performed when you specify variables in the action string. The format of the action string is as follows:

<arg>::=constant/%var
%var::=<arg1>:<arg2>:..:<argN>

It is the caller's responsibility to free the allocated buffer (which is a linked list) by calling CMD_free_assignment after processing is done.

Syntax:

CMD_ASSIGNMENT_BUF *CMD_get_assignment (CMD_PROC_DATA *data)

Arguments:

• data: Pointer to Interpreter data segment.

Return values:

• Pointer to assignment buffer: Pointer to the retrieved assignment buffer.

This function scans the variable table for the variable you specify and then returns the appropriate value and status.

Syntax:

CS_RETCODE CMD_get_bvar(CMD_PROC_DATA *data, 

CS_CHAR *label, 
CS_VOID **value, 
CS_INT *len, 
CS_VOID **template)

Arguments:

• data: Pointer to the local data segment for the command processor.

• label: Field that specifies the name of the binary variable.

• value: Indirect pointer to the data buffer in which the binary value is saved (return parameter).

• len: Integer pointer to save length of the buffer (return parameter).

• template: Indirect pointer to the binary data template structure. If used, it describes the fields and structure of the binary variable (return parameter).

Return values:

• CS_SUCCEED: The variable is defined and its value has been stored in the destination specified.

• CS_FAIL: The variable does not exist or it is not a binary variable.

This function allocates an assignment buffer, parses the current action string, and stores the results in the buffer of a linked list. A difference between this function and the CMD_get_assignment is that, with this function, the linked list node can hold binary data.

Variable substitution is performed when you specify variables in the action string. The format of the action string is as follows:

<arg>::=constant/ASCII variable/Binary variable
%var::=<arg1>:<arg2>:..:<argN>

It is the caller's responsibility to free the allocated buffer (which is a linked list) by calling CMD_free_bvar_assignment after processing is done.

Syntax:

CMD_BVAR_ASSIGNMENT_BUF *CMD_get_bvar_assignment(CMD_PROC_DATA *data)

Arguments:

• data: Pointer to Interpreter data segment.

Return values:

• Assignment buffer: Pointer to assignment buffer.

This function scans the variable table for the ASCII variable you specify and then returns the value and status.

See also "CMD_store_var."

Syntax:

CS_RETCODE CMD_get_var(CMD_PROC_DATA *data, 

char *label, 
char *value)

Arguments:

• data: Pointer to the local data segment for the command processor.

• label: Name of the variable.

• value: Buffer where the value of the variable is to be stored.

Return values:

• CS_SUCCEED: The variable is defined and its value has been stored in the destination specified.

• CS_FAIL: The variable does not exist or is not an ASCII variable.

This function locks the mutex associated with regular expression management.

See also "CMD_unlock_regexpr."

Syntax:

void CMD_lock_regexpr(void)

This function is superseded by CMD_get_assignment() which has no limit on the number of arguments.

This function scans the current action string to locate the destination variable and the three arguments for the action function. The format for the action string is as follows:

%var ::=<arg1>:<arg2>:<arg3>
where <arg> is a variable <%var> or a value (for example, %x=%y:10:%z)

Syntax:

CS_RETCODE CMD_parse_assignment(CMD_PROC_DATA *data, 

PARSE_BUF *buf)

Arguments:

• data: Pointer to the local data segment for the command processor.

• parse_buf: Pointer to a parse buffer.

Return values:

• CS_SUCCEED: Parse of the string was successful.

• CS_FAIL: Parse of the string failed.

This function stores information about a binary ASDL program variable in the command processor or program variable table or updates the variable if it already exists in the table.

See also "CMD_get_bvar."

Syntax:

CS_RETCODE CMD_store_bvar(CMD_PROC_DATA *data, 

CS_CHAR *label, 
CS_VOID *value, 
CS_INT len, 
CS_VOID * void (*template_destructor)(CS_VOID *template))

Arguments:

• data: Pointer to the local data segment for the command processor.

• label: Name of the binary variable.

• value: Void pointer to the data buffer in which the binary value is saved.

• len: Length of the buffer.

• template: Pointer to the binary data template structure. If used, it describes the fields and structure of the binary variable.

• template_destructor: Pointer to the destructor function to be called to deallocate the template. If it is not required, set it to NULL.

Return values:

• CS_SUCCEED: The variable was successfully stored or updated in the variable table.

• CS_FAIL: The variable was not stored in the variable table.

This function stores an ASCII ASDL program variable in the command processor or program variable table. If the program variable already exists in the table, this function updates it.

See also "CMD_get_var."

Syntax:

CS_RETCODE CMD_store_var(CMD_PROC_DATA *data, 

char *label, 
char *value)

Arguments:

• data: Pointer to the local data segment for the command processor.

• label: Name of the variable.

• value: Value of the variable.

Return values:

• CS_SUCCEED: The variable was successfully stored or updated in the variable table.

• CS_FAIL: The variable was not stored in the variable table.

This function stores an ASCII ASDL program variable in the command processor or program variable table. If the program variable already exists in the table, this function updates it. In addition, this function formats the variable based on the maximum field length, padding the field with leading zeroes. If the string length is greater than the total field length specified, the truncated value is saved in the variable.

See also "CMD_get_var."

Syntax:

CS_RETCODE CMD_store_zero_pad_var(CMD_PROC_DATA *data, 

char *label, 
char *value, 
CS_INT total_field_len zero_pad)

Arguments:

• data: Pointer to the local data segment for the command processor.

• label: Name of the variable.

• value: Value of the variable.

• zero_pad: Maximum field length to be used when formatting this numerical field.

Return values:

• CS_SUCCEED: The variable was successfully stored or updated in the variable table.

• CS_FAIL: The variable was not stored in the variable table.

This function unlocks the mutex associated with regular expression management.

See also "CMD_lock_regexpr."

Syntax:

void CMD_unlock_regexpr(void)

This function adds an action to the action table in the main Interpreter State Table action tree. If the action already exists, the new action overrides the existing action.

Syntax:

CS_RETCODE CMD_user_actions(ACTION_RECORD *action_tbl)

Arguments:

• action_tbl: User action table. Must be terminated with the last entry having an action equal to NULL.

Return values:

• CS_SUCCEED: User-specific State Table action successfully added.

• CS_FAIL: User actions could not be installed into the Interpreter action table.

This function purges all performance data that have been stored for more than a specified number of days. The default value of a_days is 3 days if it is not provided.

For more information about using functions, see "Oracle Execution Examples."

Affected tables:

• tbl_alarm_log

• tbl_event_log

• tbl_process_info

This function deletes a system alarm code from tbl_system_alarm.

For more information about using functions, see "Oracle Execution Examples."

This function deletes ASAP application registration information from the Control database (tbl_appl_proc).

For more information about using functions, see "Oracle Execution Examples."

This function deletes an alarm center definition from the control database (tbl_alarm_center).

For more information about using functions, see "Oracle Execution Examples."

This function deletes an administration system code from the database (tbl_code_list).

For more information about using functions, see "Oracle Execution Examples."

This function deletes an ASAP component from tbl_component.

For more information about using functions, see "Oracle Execution Examples."

This function deletes a database threshold definition from tbl_db_threshold.

For more information about using functions, see "Oracle Execution Examples."

This function deletes an ASAP event type from the database (tbl_event_type).

For more information about using functions, see "Oracle Execution Examples."

This function deletes a file system threshold definition from tbl_fs_threshold.

For more information about using functions, see "Oracle Execution Examples."

This function deletes a listener entry from tbl_listeners.

For more information about using functions, see "Oracle Execution Examples."

This function deletes a name/value pair from the database (tbl_name_value_pair).

For more information about using functions, see "Oracle Execution Examples."

This function lists listener entries associated with an NEP (tbl_listeners).

For more information about using functions, see "Oracle Execution Examples."

This function lists system alarms contained in tbl_system_alarm.

For more information about using functions, see "Oracle Execution Examples."

This function lists ASAP application registration information for the specified appl_cd or all applications from the Control database (tbl_appl_proc).

For more information about using functions, see "Oracle Execution Examples."

This function lists alarm center definitions from the control database (tbl_alarm_center).

For more information about using functions, see "Oracle Execution Examples."

This function lists Administration System code(s) from tbl_code_list.

If you invoke the function without any parameters, all rows in the table are listed.

For more information about using functions, see "Oracle Execution Examples."

This function lists ASAP components contained in tbl_component.

If you invoke the function without any parameters, all rows in the table are listed.

For more information about using functions, see "Oracle Execution Examples."

This function lists database threshold definition(s) contained in tbl_db_threshold.

If you invoke the function without any parameters, all rows in the table are listed.

For more information about using functions, see "Oracle Execution Examples."

This function lists ASAP event definitions contained in tbl_event_type.

If you invoke the function without any parameters, all rows in the table are listed.

For more information about using functions, see "Oracle Execution Examples."

This function lists file system threshold definitions contained in tbl_fs_threshold.

If you invoke the function without any parameters, all rows in the table are listed.

For more information about using functions, see "Oracle Execution Examples."

This function lists name/value pairs from the database (tbl_name_value_pair).

If you invoke the function without any parameters, all rows in the table are deleted.

For more information about using functions, see "Oracle Execution Examples."

This function defines a system alarm which may be generated by ASAP system events. This includes the start time, interval, and end time for the alarm.

This function populates tbl_system_alarm.

Example:

The following example creates an alarm for the abnormal termination of an application process to the ADMINPGR center that is continuous on a five minute period any time of the day, type the following:

var retval number;
exec :retval := CSP_new_alarm ('ABNORMAL', 'Abnormal process termination', 'CRITICAL', '',NULL, 'N', 5, 0, 1440, 'ADMINPGR');

print retval;

For more information about using functions, see "Oracle Execution Examples."

This function defines a new ASAP client or server application in tbl_appl_proc.

For more information about using functions, see "Oracle Execution Examples."

Example:

To configure ASAP to manage and monitor this processes, enter the following commands. This example assumes this processes is executed automatically at startup and the Low level diagnostics are active.

var retval number;
exec :retval := CSP_new_appl (4, 'S', 'NEPAXE', 'CONTROL2','Y', 'LOW', 'NEPAXE.diag', 'NEP for AXE Switches')

Once the control servers are started on their respective machines, you can start and shut down the application processes automatically from the master system.

This function defines an alarm center to which alarm notifications are sent by the Control server. This function populates tbl_alarm_center.

Syntax:

var retval number;
exec :retval :=  CSP_new_center ('alarm_center', 'control_prog', ['description'], ...);

Example:

In the following example, admin.sh is the ADMIN center and adminpg is the ADMINPGR center. You must place the final versions of these programs in the ASAP programs directory and identify them using the environment variable $PROGRAMS.

var retval number;
exec :retval :=  CSP_new_center ('ADMIN', 'admin.sh', 'General Admin. Center');

For more information about using functions, see "Oracle Execution Examples."

This function populates tbl_code_list with core or custom code used by ASAP. For instance, this function to identify codes that track the cartridges deployed within ASAP.

For more information about using functions, see "Oracle Execution Examples."

This function defines an ASAP component in a territory and adds it to database table tbl_component.

For more information about using functions, see "Oracle Execution Examples."

This function defines database and/or transaction log thresholds to be used by the Control server, and writes the information to tbl_db_threshold. The Control server monitors the database/transaction log size and issues the appropriate data event/transaction event when the threshold is exceeded.

Syntax:

var retval number;
exec :retval :=  CSP_new_db_thresh ('asap_sys', 'db_name', 'db_threshold', 'tran_threshold', 'data_event', 'tran_event')

Example:

var retval number;
exec :retval :=  CSP_new_db_thresh ('PROD', 'SDB_P01_asap', 80, 20, 'DB2FULL', 'TRANFULL';

in this example, the database threshold is set to 80 percent. If the database becomes more than 80 percent full, the DB2FULL system event is issued. This command also sets the transaction log threshold for the database. When the transaction log for the database exceeds 20 MB, the TRANFULL system event is issued.

Database thresholds must be defined in the component table.

For more information about using functions, see "Oracle Execution Examples."

This function defines an “event type" within ASAP, and optionally, the associated “alarm code" that is associated with the event. System events can be generated when an error condition is encountered in ASAP. CSP_new_event populates tbl_event_type.

For more information about using functions, see "Oracle Execution Examples."

Syntax:

var retval number;
exec :retval :=  CSP_new_event ('event_type', ['description'], ['alarm_code'], [“alarm_action'];

Example:

The following example shows an ABNORMAL system event mapped to the ABNORMAL alarm.

var retval number;
exec :retval :=  CSP_new_event ('ABNORMAL', 'Abnormal Process Termination Event', 'ABNORMAL', 'E';

This function defines a file system threshold to be used by the Control server. The Control server monitors the file system size and if the threshold is exceeded, the appropriate system event is generated. File system threshold information is stored in tbl_fs_threshold.

For more information about using functions, see "Oracle Execution Examples."

This function adds a listener entry to tbl_listeners. You must configure this table to allow the SARM to start up socket listeners for incoming SRP requests. As well, every Java-enabled NEP must maintain a dedicated connection to its JInterpreter.

For more information about using functions, see "Oracle Execution Examples."

This function defines parameters (name value pairs) that are required to maintain the control database. Typical parameters include “audit trail window", “log retention window", etc. This information is stored in tbl_name_value_pair.

For more information about using functions, see "Oracle Execution Examples."

class ASC_Main: public Config, public ASC_ThreadAppl
{
public:
ASC_Main (int argc, char *argv[]);
~ASC_Main (void);
int threadMain(void **Rtn) { return CS_SUCCEED; }; 
CS_RETCODE config_param_init (void);
CS_RETCODE ctlib_init (void);
void process_input (void);
CS_RETCODE initialize (void);
void default_signal_handlers (void);
CS_RETCODE install_signal_handler (CS_INT signum, CS_VOID * func);
virtual CS_RETCODE appl_initialize (void) = 0;
virtual void appl_cleanup (void) {};
void startup(void);
protected:
int m_argc_;
// Local copy of main()'s argc.
char **m_argv_;
// Local copy of main()'s argv;
DIAG_CONFIG m_diag_cfg;
// Initialization structure use by class Diagnosis
// static Diagnosis *m_diag;
// Original diag object pointer.
EventAgent * m_event_ea_;
// EventAgent service thread object pointer.
char m_SQLSrvName[80];
// Physical SQL Server for the Control DB.
char m_MasterCtrlSvr[80];
// Logical Master Control Server.
static CS_CONTEXT *m_client_context_;
// Context of the client process.
// The following routines are Unix signal handlers.
// They are installed by Sybase's ct_callback() 
// routine in default_signal_handlers() method.
// They can also be used as other signal's handler 
// which should be installed separately by
// install_signal_handler() method.
static void terminate_signal(int sig);
static void core_dump_signal(int sig);
static void child_terminate(int sig);
static void ignore_signal(int sig);
static void terminate_pgm(void);
// routine used by signal handlers.
static ASC_Main *m_this_ptr;
// copy of this pointer. 
};

ASC_Main (int argc, char *argv[]);

This constructor uses all the initialization methods to establish the required client application environment. If the ASC_Main object instantiates successfully, the next step is to execute an application-specific code.

Arguments:

An ASC_Main object must be initialized with the following input arguments:

• argc: The number of elements in the argv[ ] array. You must pass the argc of main () to this argument.

• argv: An array of string pointers. You pass the argv of main () to this argument. Valid elements are:

  • applName – Application name

  • -c ctrlSvrName – Master control server name

  • -l diagLevel – Diagnostic level

  • -f diagFile – Diagnostic file name

You must override appl_initialize and appl_cleanup using the application-specific methods provided in the application programmers' subclasses. The overridden methods can use any facility provided by this class library and spawn as many threads as required, as long as they do not violate the rules.

Syntax:

virtual CS_RETCODE appl_initialize (void) = 0;
virtual void appl_cleanup (void) {};

The startup method is used to start the execution of application code in appl_initialize () that you have defined. After the ASC_Main object has been successfully instantiated, startup () should be called to pass program control to the application.

Syntax:

void startup(void);

Required by ASC_ThreadAppl as the thread start function.

Syntax:

int threadMain(void **Rtn) { return CS_SUCCEED; };

This method initializes the configuration B tree.

Syntax:

CS_RETCODE config_param_init (void);

This method initializes client/server related config parameters.

Syntax:

CS_RETCODE ctlib_init (void);

This method processes the command line input parameters. It terminates the program if the input is improper.

Syntax:

void process_input (void);

Client initialization method.

Syntax:

CS_RETCODE initialize (void);

This function installs the signal callback handlers.

Syntax:

void default_signal_handlers (void);

This method installs handler func for signal signum.

Syntax:

CS_RETCODE install_signal_handler (CS_INT signum, CS_VOID * func);

This pure virtual function is the abstract method for application specific activities. Application programmers should override this function in their subclasses with their self-defined methods.

Syntax:

virtual CS_RETCODE appl_initialize (void) = 0;

This pure virtual function is the abstract method for application specific cleanup activities. Application programmers should override this function in their subclasses with their self-defined methods if there's any special cleanup to be performed at termination.

Syntax:

virtual void appl_cleanup (void) {};

class Diagnosis: public Config, public ASC_ThreadAppl {
public:
Diagnosis (DIAG_CONFIG *cfg, ASC_MsgQueue *asc_msgq,

char *thrName);

// Constructor to initialize diagnostic environment with
// configuration structure **cfg**.
Diagnosis (char *thrName = "unknown"):ASC_ThreadAppl

(thrName) {};

// Do nothing constructor.
~Diagnosis(void);
virtual CS_RETCODE initialize (DIAG_CONFIG *cfg);
virtual void diag (VOIDPTR UNUSED(ptr), DIAG_LEVEL level,

char *type,int line, char *file, char *fmt

virtual void  diag_format (VOIDPTR ptr, DIAG_LEVEL

level,char *type, int line, char *file, void
(*format_fn)(FILE *outfile, VOIDPTR ptr)) {};

virtual void hex_dump (DIAG_LEVEL level, char *type, 

int line, char *file,CS_BYTE *buf, int buf_len) {};

virtual void rpc_dump (DIAG_LEVEL level, int line, 

char *file) {};

virtual void stack_trace (DIAG_LEVEL level, char *type,

int line, char *file) {};

void * service_mgr (void);
static CS_BOOL m_diag_queue;
static ASC_Mutex m_diag_mtx_;
int threadMain(void **Rtn);
protected:
void multi_diag_init (void);
//
CS_RETCODE print_queue (void);
// This method is used to take an message entry from
// the diag queue and print the associated
// message to the diag file.
CS_RETCODE create_srv_thread (void);
// This method creates a service thread used to process
// diag messages on the diag queue and print 
// them to the diag file on a FIFO basis.
DIAG_LEVEL set_diag_level (char *level_msg);
char *set_diag_level_msg (DIAG_LEVEL level);
void pre_write_diag_file (char *file);
void post_write_diag_file (DIAG_LEVEL level,

char *file, long max_size);

void diag_file_open(char *filename);
void diag_file_move(char *filename);
void dump_configuration(void);
static FILE *m_diag_outfile;
private:
static int m_last_day;
static long m_log_file_max;
static DIAG_FILE *m_diag_files;
static CS_INT m_diag_idx;
static DIAG_LEVEL m_diag_level;
static DIAG_CONFIG m_diag_config;
static CS_BOOL m_diag_line_flush;
static CS_INT m_MAX_DIAG_FILES;
static ASC_MsgQueue *m_msgq;
// the pointer to the message queue object used for
// queueing all diag messages.
};

This class has two constructors. To create the service thread, use the attachThread method in ASC_ThreadAppl class. To provide dequeueing and printing services, service_mgr is called in the thread context.

Syntax:

Diagnosis (DIAG_CONFIG *cfg, ASC_MsgQueue *asc_msgq, 

char *thrName);

Diagnosis (char *thrName = "unknown"):ASC_ThreadAppl

(thrName){};

Arguments:

• cfg: Initializes Diagnosis-related global settings, diagnostic files, and spawn service thread if required.

• asc_msgq: Constructs custom Diagnosis objects. The newly-created object uses the settings, diagnostic files, and message queue initialized when instantiating the very first Diagnosis object in the ASC Main's constructor.

• thrName: The thread Name in which the object is instantiated. It appears at the end of each diagnostic message indicating in which thread the message is generated.

ASAP Application Server runtime diagnostic method diag is designed to generate diagnostic messages in the required format anywhere in the application.

Syntax:

virtual void diag (VOIDPTR UNUSED(ptr), DIAG_LEVEL level,

char *type, int line, char *file, char *fmt, ...);

Arguments:

• ptr: Only used by the debugger within the Interpreter.

• level: The diagnostic level of this particular function call.

• type: Character pointer identifying type or functional origin of the function call. Only the first 15 characters of this function call appear in the diagnostic file.

• line: The line number of the function in the source file, _ _LINE_ _.

• file: The file name from which the function was called, _ _FILE_ _.

• fmt: Character pointer to a sprintf format buffer containing the diagnostic message itself.

• ...: Variable number of parameters following the sprintf format.

Initializes the diagnostic environment with configuration structure **cfg**.

Syntax:

virtual CS_RETCODE initialize (DIAG_CONFIG *cfg);

SAP Application Server User Specified Diagnostic Formatting method.

Syntax:

virtual void diag_format (VOIDPTR ptr, DIAG_LEVEL

level,char *type, int line, char *file, void
(*format_fn)(FILE *outfile, VOIDPTR ptr)) {};

This function produces a hexadecimal dump of a character buffer in the server diagnostic logfile.

Syntax:

virtual void  hex_dump (DIAG_LEVEL level, char *type, 

int line, char *file,CS_BYTE *buf, int buf_len) {};

This function prints the RPCs supported by the Open Server to the diagnostic logfile.

Syntax:

virtual void  rpc_dump (DIAG_LEVEL level, int line, 

char *file) {};

virtual void  stack_trace (DIAG_LEVEL level, char *type, int line, char *file) {};

This member function is the start function of the queue service thread used to take diagnostic messages off the diag queue and print them to the diag file.

This method must only be used in conjunction with create_srv_thread() method and must not be used elsewhere.

Syntax:

void * service_mgr (void);

This flag indicates whether diag messages are sent to a message queue. If CS_TRUE is set, all messages are sent to the queue. If this flag is set to CS_FALSE after the service thread has been created, the service thread terminates after taking all messages off the queue and processing them.

Syntax:

static CS_BOOL m_diag_queue;

This method is a pointer to the mutex used to synchronize access to the diag file.

Syntax:

static ASC_Mutex m_diag_mtx_;

ASC_ThreadAppl required thread start function.

Syntax:

int threadMain(void **Rtn);

class Event: public Diagnosis
{
public:
Event (char * thrName =“Event"):

m_eventq_(default_eventq), Diagnosis(thrName) {};

void event(char *event_type, short line, char *file, char *fmt, ...);
// ASAP event logging method.
};

The Event class uses a default event message queue to pass event messages to the EventAgent thread. A pointer to that default queue is recorded into data member m_eventq_ when an object is constructed.

Event (char * thrName = “Event"):

m_eventq_(default_eventq), Diagnosis(thrName)

You pass the thread name of the creating thread to the constructor when you instantiate the Event object. This thread name appears at the end of the diagnostic message logged into the diagnostic file. If no thread name is passed when instantiating an Event object, the event is taken as the name by default.

Arguments:

• event_type: Specifies the system event to be generated. This code is used to determine the operation to perform from the configuration tables.

• line: Line in source file where the system event was generated. Should be __LINE__.

• file: Source file where the system was generated. Should be __FILE__.

• fmt: sprintf() type format string specifying cause of the system event.

• ...:Variable number of parameters following the sprintf() format.

event:

ASAP event logging method.

Syntax:

void event(char *event_type, short line, char *file,

char *fmt, ...);

typedef struct {
int operation;
char event[APPL_EVENT_L+1];
char source_file[SOURCE_FILE_L+1];
short source_line;
char reason[APPL_REASON_L+1];
} CONTROL_AGENT_MSG;
class EventAgent: public ASC_ThreadAppl 
{
public:
EventAgent (ASC_MsgQueue *eventq = ::default_eventq,

ClntProcMgr *sql_cpp = ::default_sql_cpp, 
ClntProcMgr *ctrl_cpp = ::default_ctrl_cpp);

// This constructor initializes private data members,
// ~EventAgent (void) {};
int threadMain(void **Rtn);
// ASC_ThreadAppl required thread start routine.
void startup (void);
void start_service (void);
CS_BOOL m_should_terminate;
virtual void alarm (time_t seconds, ASC_MsgQueue *q, 

int *msg, long msg_operation) {};

ASC_Mutex m_ea_mtx_;
protected:
void write_event (ClientProc *sql_cp, ClientProc

*ctrl_cp, CS_CHAR *event, CS_CHAR *file, 
CS_INT *line, CS_CHAR *reason);

static CS_RETCODE sys_event_handler (CS_VOID *sql_cp,

CS_VOID *data,CS_RETCODE UNUSED(restype), 
CS_BOOL *UNUSED(not_done));

private:
ASC_MsgQueue *m_eventq_;
// Message queue used to pass event messages to the
// agent thread.
ClntProcMgr *m_ctrl_cpp_;
// Pointer to master control server connections 
// manager object. 
ClntProcMgr *m_sql_cpp_;
// Pointer to control sql server connections 
// manager object. 
};

EventAgent (ASC_MsgQueue *eventq = ::default_eventq,

ClntProcMgr *sql_cpp = ::default_sql_cpp, 
ClntProcMgr *ctrl_cpp = ::default_ctrl_cpp);