SDS C API Notes

          

Home
Up

Overview of Client        

 SDS C API

1. 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.

1.1 GDSInitCache - USHORT EXPORT GDSInitCache

(LPUCHAR lpszDBPath,

 

USHORT NumEntries,

 

MDR_List LoadList);

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 MDR’s 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.

1.2 GDSCacheOn - USHORT EXPORT GDSCacheOn ();

This function enables caching when accessing MDRs after caching has been turned of with the function GDSCacheOff.

1.3 GDSCacheOff - USHORT EXPORT GDSCacheOff

( BOOL ClearCache );

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.

2. SDS Global Functions

The following is a list of functions that are used globally with SDS encoder and decoder functions.

2.1 GDSOpen - LPGDSCB EXPORT GDSOpen

LPCHAR   lpszDBPath,

 

LPUSHORT lpusErrorCode );

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.

2.2 GDSGetMsgSize - USHORT EXPORT GDSGetMsgSize

LPGDSCB lpGDScb );

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. 

2.3 GDSGetElementInfo - USHORT EXPORT GDSGetElementInfo,

(LPGDSCB  lpGDScb

 

LPUCHAR  lpuszElmID,

 

LPUCHAR  lpuszDataType

 

LPUSHORT lpusMinSize

 

LPUSHORT lpusMaxSize

 

LPUCHAR  lpuszMntryFlg

 

LPUSHORT lpusRptFctr );

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.

2.4 GDSSetSystem - USHORT EXPORT GDSSetSystem

( LPGDSCB lpGDScb,

 

LPCHAR lpuszSystem

 

USHORT chkMdrTm);

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.

2.5 GDSClose - USHORT EXPORT GDSClose

( LPGDSCB lpGDScb );

This function is used to terminate SDS processing.  It closes all open files and releases all dynamically allocated memory. 

3. Decoder Functions

The decoder functions are used to parse a SDS message and return the individual data elements from the message.

3.1 GDSAllocMsg - USHORT EXPORT GDSAllocMsg

( LPGDSCB lpGDScb,

 

LPUCHAR lpuszGDSMsg);

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.

3.2 GDSGetMsgID - USHORT EXPORT GDSGetMsgID

 ( LPGDSCB lpGDScb,

 

LPUCHAR lpszMsgID,

 

LPUCHAR lpuszVersion );

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.

3.3 GDSGetNextSeg - USHORT EXPORT GDSGetNextSeg

( LPGDSCB  lpGDScb,

 

LPUCHAR  lpszSegId,

 

LPUSHORT lpusNest );

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.

3.4 GDSGetNextElem - USHORT EXPORT GDSGetNextElem

( LPGDSCB lpGDScb,

 

LPUCHAR lpszElemId,

 

LPUCHAR lpszElemVal );

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.

4. Encoder Functions  

The encoder functions are used to build a SDS message.

4.1 GDSPutMsgID - USHORT EXPORT GDSPutMsgID

( LPGDSCB lpGDScb,

 

LPUCHAR lpuszMsgId,

 

LPUCHAR lpuszVersion );

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

4.2 GDSPutAction - USHORT EXPORT GDSPutAction

( LPGDSCB  lpGDScb,

 

LPUCHAR  lpuszAction);

This function is used to add the application action code to the inbound SDS message.

4.3 GDSPutApplID - USHORT EXPORT GDSPutApplID

( LPGDSCB  lpGDScb,

 

LPUCHAR  lpuszApplID);

This function is used to add the SDS application id to the inbound SDS message.

4.4 GDSPutSubsetID - USHORT EXPORT GDSPutSubsetID

( LPGDSCB  lpGDScb,

 

LPUCHAR  lpuszSubsetID);

This function is used to add the subset id to the inbound SDS message.

4.5 GDSPutSeg - USHORT EXPORT GDSPutSeg

( LPGDSCB  lpGDScb,

 

LPUCHAR  lpuszSegId,

 

USHORT   usNstLvl);

This function is used to start a new message segment within the SDS message. The values passed are actually accumulated until GDSGetMsg is called.

4.6 GDSPutCompElem - USHORT EXPORT GDSPutCompElem

( LPGDSCB lpGDScb,

 

LPUCHAR lpuszCompId);

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().

4.7 GDSPutElem - USHORT EXPORT GDSPutElem

( LPGDSCB lpGDScb,

 

LPUCHAR lpuszElementId,

 

LPUCHAR lpuszElementValue );

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).

4.8 GDSCompEnd - USHORT EXPORT GDSCompEnd

(LPGDSCB lpGDScb);

This function signals the end of a composite element when building a SDS message.

4.9 GDSGetMsg

 USHORT EXPORT GDSGetMsg( LPGDSCB lpGDScb, PUCHAR Buf );

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.

5. Packet Functions  

The SDS Packet functions allow the application to send and receive large message in packets.

5.1 GDSInitPacket - USHORT EXPORT GDSInitPacket

( LPGDSCB  lpGDScb,

 

LPUCHAR  lpuszGDSMessage );

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.

5.2 GDSGetPacket - USHORT EXPORT GDSGetPacket

( LPGDSCB  lpGDScb,

 

LPUCHAR  lpuszPacket,

 

USHORT   usPacketSize,

 

LPUSHORT lpusLastBlock );

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.

5.3 GDSResetPacket

 USHORT EXPORT GDSResetPacket (LPGDSCB lpGDScb );

This function releases any previous message and prepares the SDS API to start receiving packets.

5.4 GDSPutPacket - USHORT EXPORT GDSPutPacket

( LPGDSCB  lpGDScb,

 

LPUCHAR  lpuszPacket,

 

LPUSHORT lpusLastBlock );

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.

6. Database Functions  

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.

6.1 GDSOpenDB - USHORT GDSEXPORT GDSOpenDB

( LPGDSCB lpGDScb);

This function opens the MDR database files for use.

6.2 GDSCloseDB - USHORT GDSEXPORT GDSCloseDB

( LPGDSCB lpGDScb, BOOL bDealloc);

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.

6.3 GDSSaveMDR - USHORT GDSEXPORT GDSSaveMDR

 LPGDSCB lpGDScb,

 

LPUCHAR lpuszMDR );

This function is used to add MDRs to the local MDR database.

7. Utility Functions  

The following functions are intended to assist programmers with debugging of their applications.

7.1 GDSAddMDRSimulated - USHORT GDSEXPORT GDSAddMDRSimulated

 LPGDSCB lpGDScb,

 

PUCHAR lpszMsgId,

 

PUCHAR lpszMsgVer);

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.

7.2 GDSStartLogging - USHORT EXPORT GDSStartLogging

 LPGDSCB lpGDScb,

 

PUCHAR lpuszLoggingFileName,

 

HORT   bAppend,

 

SHORT   bReformatGDS );

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. 

7.3 GDSPrintLog - USHORT EXPORT GDSPrintLog

 LPGDSCB lpGDScb,

 

LPCHAR  lpszMessage );

This function prints a message to the SDS logging file. The SDS logging file is used to keep a trail of all SDS activity.

7.4 GDSPrintLogNL - USHORT EXPORT GDSPrintLogNL

 LPGDSCB lpGDScb,

 

LPCHAR  lpszMessage );

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.

7.5 GDSStopLogging - USHORT EXPORT GDSStopLogging

 LPGDSCB lpGDScb );

This function closes the SDS logging file.