SDS Cache Functions
The following set of functions should be used to increase efficiency when using the SDS functions. These functions allow for the MDR to be stored into cache so that the MDR does not have to be read and parsed every time the MDR is used. The use of these functions will be beneficial to the application if the same MDR is used multiple times.
This function initializes the caching of MDRs. It allows for the user to specify how many MDRs to store in cache as well as what MDRs to use and where to find them. The user can specify through NumEntries, how many MDRs to put into cache at one time. This is the maximum number of entries that will be stored in cache. The user can have MDRs loaded permanently and temporarily into cache. The MDRs that the user wishes to loaded permanently will be contained within the MDR_List structure along with the number of MDRs that are permanently being stored. The difference between the Num_Entries and the number of MDRs loaded permanently into cache will be the number of MDRs that are temporally loaded. Once all the temporary slots are filled, a new MDR being accessed that is not already loaded into cache will replace a temporary MDR.
This function enables caching when accessing MDRs after caching has been turned of with the function GDSCacheOff.
This function disables the use of caching when accessing MDRs. This function will free up the memory used to store the MDRs if the ClearCache parameter is TRUE. If the ClearCache parameter is FALSE, the Cached MDRs will remain in memory, but the MDRs will be retrieved from the data base for message processing. If this function is called with ClearCache set to FALSE, the use of cached MDRs can be restarted with a call to GDSCacheOn otherwise, GDSInitCache must be called to reallocate the cache.
The following is a list of functions that are used globally with SDS encoder and decoder functions.
This function allocates and initializes a SDS control block. It opens the MDR database and returns a pointer to the SDS control block. All other function calls require this pointer value as their first parameter.
This function returns the estimated size of the SDS message that will be built when GDSGetMsg is called. The size is an estimate in that it may be equal or it may be slightly too large. No situations have been found where this value is too small. Be sure to add 1 to the value returned for the null byte.
This function is used to return the attributes of lpuszElmID to the application. The function locates the first occurrence of lpuszElmID within the MDR and returns the information associated with that element to the application.
This function sets the system in the SDS control block. The default system is TPF for the ¤¤RES system (Note: ¤ stands for the Change Key). If not in the ¤¤RES system the system must be set. The message string delimiter set is choosed according the system. There are three character sets: ASCII, ALC and VAX. If the system is ALC, ALC character set is the delimiter set. If the system is VAX, VAX character set is the delimiter set. All other systems use the default ASCII character set. If the chkMdrTm is non-zero, the MDR time stamp is checked with the host every time and the newer version of the MDR is downloaded automatically and saved to the local database. Otherwise, SDS API uses the MDR in the local database. The default is to check the MDR time stamp.
This function is used to terminate SDS processing. It closes all open files and releases all dynamically allocated memory.
The decoder functions are used to parse a SDS message and return the individual data elements from the message.
This function is used to pass a complete SDS message to the SDS API. When called, the SDS API will purge any previous message in memory, make a copy of the SDS message and retrieve the Message Definition Record (MDR) in preparation for the decoding process.
This function return the SDS message ID and, optionally, the message version. If message version is not needed, pass a NULL value (long binary 0) in its place.
This function returns the next segment ID and nesting level in the message. Upon return, the SDS API is properly positioned to start processing elements for this segment.
This function returns the next element value and its element identifier or the next composite identifier from the SDS message. If the next element in the message stream is the first component data element of a composite, the composite identifier will be returned and lpszElemVal will be set to NULL.
The encoder functions are used to build a SDS message.
This function tells the SDS API to begin building a message. When called, this function retrieves the corresponding message definition record (MDR) and create structures in memory in preparation to start accumulating segment and element information
This function is used to add the application action code to the inbound SDS message.
This function is used to add the SDS application id to the inbound SDS message.
This function is used to add the subset id to the inbound SDS message.
This function is used to start a new message segment within the SDS message. The values passed are actually accumulated until GDSGetMsg is called.
This function indicates that a composite will be placed into the message data stream. The composite ids are actually accumulated until the function GDSGetMsg is called. At that time, the SDS message is built according to the definition laid out in the message definition record (MDR). In order for component data elements to be put into the SDS message with the function GDSPutElem(), the Composite must first be placed into the SDS message with a call to GDSPutCompElem().
This function puts a data element or a component data element in the SDS message. The element IDs and values are actually accumulated until the function GDSGetMsg is called. At that time, the SDS message is built according to the definition laid out in the message definition record (MDR).
This function signals the end of a composite element when building a SDS message.
This function builds the SDS message from data accumulated during the GDSPutMsgID, GDSPutAction, GDSPutSeg, GDSPutApplID, GDSPutCompElem and GDSPutElem function calls. The message is built in the string Buf and returned to the application for further handling.
The SDS Packet functions allow the application to send and receive large message in packets.
This function initializes the packetizing routines. The message to be packetized is passed in the string parameter lpuszGDSMessage. Subsequent calls to GDSGetPacket will return the packets that comprise the message in lpuszGDSMessage.
This function returns the next packet (SDS message block) and, if this is the last block, the lpusLastBlock flag is set. The string returned will have the maximum length of usPacketSize. Be sure the string is at least usPacketSize+1 bytes long or a General Protection Fault (GPF) will occur.
This function releases any previous message and prepares the SDS API to start receiving packets.
This function passes the SDS API the next packet (SDS message block). If this block contains a SDS end of message delimiter, the lpusLastBlock flag is set. In VB, be sure to leave space for the null byte that is appended when the VB string is converted to a C string. The SDS API is ready to parse the message string right after the first packet is successfully put.
The following functions are used to update the local MDR database once the application has downloaded the MDR from the host. SDS uses CTree database.
This function opens the MDR database files for use.
This function is used to close the MDR database files. If bDealloc is set to 1, it will free all memory allocated for MDR file use in the control block.
This function is used to add MDRs to the local MDR database.
The following functions are intended to assist programmers with debugging of their applications.
This function is used to add an MDR to the local Ctree data base. The MDR to be added must be in a text file called mdrdb.fil in the same directory specified in the GDSOpen call.
This function opens the SDS logging file. If a logging file is already open, it closes the old logging file before opening a new one. Any pre-existing logging file with the same name is overwritten unless the bAppend flag is non zero.
This function prints a message to the SDS logging file. The SDS logging file is used to keep a trail of all SDS activity.
This function prints a message to the SDS logging file. A carriage return is automatically appended to the message. The SDS logging file is used to keep a trail of all SDS activity.