═══ 1. Licensing agreement ═══

The term LICENSE is used to refer to the ASCII file containing a copy of this 
license.  The term PACKAGE here is used to refer to the header files, the 
libraries, the documentation, and LICENSE. The term AUTHOR is used to refer to 
the developer of PACKAGE. 

PACKAGE is copyrighted (c) 1993-1995 by its AUTHOR, Lawrence W. Salomon, Jr. 
and is the sole property of AUTHOR. 

You are hereby granted a license to use PACKAGE in your applications and freely 
distribute PACKAGE if and only if the following condition(s) are met: 

o All files in PACKAGE are included in the distributed files and remain in 
  their original form. 

o If the contents of the PACKAGE are distributed using any of the file 
  compression programs available (PKZIP, ZIP, ZOO, etc.), LICENSE must not be 
  included in the compressed file but instead must remain separate. 

By using any component or any part of any component of PACKAGE, you are 
indicating that you agree to and are thereby bound to the terms of this 
license. 


═══ 2. Introduction ═══

Do you ever find yourself writing a new program and wishing that you already 
had a routine to parse the command line?  Or how about a routine that performs 
signal processing?  Or maybe a set of linked list functions?  Often times, I 
have often been in this very situation, writing new code then discovering that 
I have need of routines that should be fairly common. 

Instead of simply writing the routines for each application that required them, 
I started maintaining my own software library of commonly used routines, which 
you have here.  These routines provide easy access to a host of functions that 
you used to have to write yourself. 

The functions are separated into groups, listed below: 

o Common routines 
o Buffer routines 
o Communication routines 
o Debugging routines 
o File routines 
o Link-list routines 
o Memory allocation routines 
o Object handling routines 
o Set routines 
o Signal routines 
o Sprite routines 
o String routines 
o Screen I/O routines 
o Windowing routines 

Additionally, the following topics are also available: 

o Licensing agreement 
o Using Common/2 in your applications 
o About errors, bugs, and suggestions 
o What's New in this Release 

A couple of notes are needed: 

o As you use Common/2, you may notice that the library seems to have been built 
  out of "spare parts", because there is lacking a tight level of integration. 
  This is true, and I hope to resolve this in the near future by taking such 
  steps as having each function return an error code (like the kernel APIs), 
  and combining the error codes (instead of having a group for the memory 
  routines, another group for the object routines, etc.).  If you have any 
  suggestions on how the library can be made to fit together better, I would be 
  most interested in hearing them. 


═══ 2.1. Using Common/2 in your applications ═══

Common/2 was compiled using IBM's C-Set++ compiler; compatibility with other 
32-bit compilers has not been tested.  It does require you to have the 
Programmer's Toolkit installed on your machine or its functional equivalent, 
however.  You should place the files common.h and cmndefs.h in a directory 
specified by the INCLUDE environment variable.  Additionally, you should place 
the .LIB files in a directory specified by the LIB environment variable and the 
.DLL files in a directory specified by the LIBPATH environment variable. 

Note that <os2.h> must be included before including <common.h>.  Do not 
explicitly include <cmndefs.h> because it is included by <common.h>.  As with 
<os2.h>, before including <common.h> you should define the appropriate 
constants to indicate which portions of the library you would like to use: 

INCL_CMNBUF         Buffer routines (CmnBuf) 

INCL_CMNCOM         Communication routines (CmnCom) 

INCL_CMNDBG         Debugging routines (CmnDbg) 

INCL_CMNFIL         File routines (CmnFil) 

INCL_CMNLST         Linked list routines (CmnLst) 

INCL_CMNMEM         Memory routines (CmnMem) 

INCL_CMNOBJ         Object routines (CmnObj) 

INCL_CMNSET         Set routines (CmnSet) 

INCL_CMNSIG         Signal routines (CmnSig) 

INCL_CMNSPR         Sprite routines (CmnSpr) 

INCL_CMNSTR         String routines (CmnStr) 

INCL_CMNVIO         VIO routines (CmnVio) 

INCL_CMNWIN         Window routines (CmnWin) 

INCL_COMMONALL      All sections 

The general purpose routines (those that begin with Cmn only) are always 
included regardless of the constants defined. 

Obtaining the Source 

While the runtime has been placed on various networks and may be distributed 
free-of-charge, the source to Common/2 has not been made public. If you are 
interested in licensing the entire source or just a module or two for your 
company, please contact the author. 


═══ 2.2. About errors, bugs, and suggestions ═══

Often, when something doesn't quite work correctly, it is because the wrong 
handle was passed to the function which returned the unexpected result. Before 
crying "wolf", you should first call CmnQueryHandle to insure that you are 
giving the function what it expects. 

If that still doesn't help, if you have some suggestions, if you have a set of 
routines that you would like to donate to the library, or if you would like to 
translate the programming reference and header files into other languages, feel 
free to send me mail via the Internet.  My address is "os2man@panix.com".  If 
you are describing what you think is a bug, please describe the steps needed to 
recreate the problem and include code when possible. 


═══ 2.3. What's New in this Release ═══

Changes resulting in release 1.7.0 include: 

o The typedefs PFNRECCOMP, PFNRECFUNC, PFNRECMED, PFNCMDARG, and PFNCMDERR were 
  all changed so that the last parameter in each is a PVOID which is passed in 
  to the function that uses these types.  The functions affected are listed 
  below: 

   - CmnLstAddRecord 
   - CmnLstAddUniqueRecord 
   - CmnLstCopyList 
   - CmnLstPruneList 
   - CmnLstQuickSortList 
   - CmnLstSearchRecord 
   - CmnLstSortList 
   - CmnLstTraverseList 
   - CmnStrParseCommandLine 

  These functions accept the new parameter - pvData - at the end of their 
  parameter list. 

  While I realize that this affects many people, I feel that the change is 
  necessary, since the only way to communicate with the callbacks previously 
  was through global variables.  These changes will allow any additional data 
  that is needed by the callbacks to be passed in as a pointer to a (local) 
  structure.  I extend my most sincere apologies for the effect that these 
  changes will have; the changes affect me just as severely. 

Changes resulting in release 1.6.1 include: 

o The function CmnFilInstallDiskette was added. 

──────────────────── 

Changes resulting in release 1.6.0 include: 

o The license was modified to allow the use of Common/2 in commercial 
  applications. 

o Added #define's to avoid problems with case-sensitivity during linking. 

o Added code to properly draw overlaying sprites. 

o The functions CmnSprSetLayering() and CmnSprQueryLayering() were added to 
  manipulate the layer of a sprite in the z-order. 

──────────────────── 

Changes resulting in release 1.5.0 include: 

o The CmnBuf routines were added. 

o The functions CmnFilCopyDiskette() and CmnFilFormatDiskette() were added. 

──────────────────── 

Changes resulting in release 1.4.0 include: 

o The library was moved from a .LIB to a .DLL in hopes of someday writing Rexx 
  interfaces for some or all of the routines.  This impacted a number of 
  things: 

   - The CmnVio routines, since CmnVioLoadMessage() assumes that messages will 
     be bound (with MSGBIND) to the DLL and not the EXE file; if an EXE uses 
     MSGBIND to bind its messages to itself, CmnVioLoadMessage() (and thus 
     CmnVioDisplayMessage(), since it is dependent on the former) would return 
     an error. 

   - If you write an application that uses non of the PM-dependent routines 
     (CmnSpr and CmnWin), and tried to run the application in a non-PM 
     environment (e.g. booting from the installation diskettes), OS/2 would 
     return an error since, by virtue of the fact that your application is 
     linked to the DLL, PM is required.  To alleviate this problem, the DLLs 
     have multiplied from two to four, and a naming convention was established 
     to allow for this. 

     The format of the DLL and LIB file names is CMN32te. "t" is the "threaded" 
     option and can be S for single-threaded or M for multi-threaded.  "e" is 
     the "environment" option and can be V for routines that do not require PM 
     (VIO), or P for routines that do require PM. 

o 16-bit support was removed.  This was due to the fact that we're in the 
  second release of a 32-bit OS/2, so 16-bit seemed rather redundant.  The code 
  for all existing functions is still there, but no new development will make 
  provisions for 16-bit compatibility, nor will the 16-bit version of the 
  library be released in this package.  Should you need this, contact me via 
  email. 

o The constant INCL_CMNLIB was renamed to INCL_COMMONALL, in the (admittedly 
  unlikely) event that a CmnLib subsystem is added. 

o The constant SPL_ERROR was renamed to SPL_ERR_ERROR to avoid conflicts with 
  the constant of the same name in <pmspl.h>. 

o Minor bugs with the CmnCom subsystem were fixed. 

o A minor bug with the CmnFilSearchFiles() function was fixed. 

o A minor bug with the CmnMemFreeMem() was fixed. 

o The CmnFilSplitFilename() function was added. 

o The CmnWinSavePosToBuffer() and CmnWinRestorePosFromBuffer() functions were 
  added and the CmnWinSavePosition() and CmnWinRestorePosition() functions were 
  modified to utilize these new functions. 

o The functions CmnStrPadString() and CmnStrStripSpace() were added. 

o The function CmnVioGetString() has been added. 

o The sprite subsystem (INCL_CMNSPR) was added. 

o All function pointer typedefs were modified to include the EXPENTRY attribute 
  to allow for non-IBM compilers. 

──────────────────── 

Changes resulting in releases prior to 1.4.0 were not documented. 


═══ 3. Common routines ═══

The purpose of this group is to provide functions which apply to all of the 
function groups.  Listed below are the functions which comprise this group: 

o CmnQueryHandle 
o CmnQueryHandleInfo 
o CmnQueryVersion 
o CmnSetHandleInfo 


═══ 3.1. CmnQueryHandle ═══

CmnQueryHandle 

Purpose 

This function returns the type of the specified handle. 

Syntax 

(USHORT)CmnQueryHandle(lhHandle);

Parameters 

lhHandle (LHANDLE) - specifies the handle to query. 

Returns 

This function returns one of the following values: 

QH_ERROR 
QH_HCCCONNECT 
QH_HCFSEARCH 
QH_HCLLIST 
QH_HCMMEM 
QH_HCOOBJECT 
QH_HCSSET 
QH_HCSSIGNAL 
QH_HCSPLAYGROUND 
QH_HCSSPRITE 

Notes 

This function does not validate the accessability of the memory corresponding 
to lhHandle.  Thus, a value that specifies an invalid memory location will 
cause the application to trap. 

Related information 

o CmnQueryHandleInfo 


═══ 3.2. CmnQueryHandleInfo ═══

CmnQueryHandleInfo 

Purpose 

This function returns information about the specified handle. 

Syntax 

(BOOL)CmnQueryHandleInfo(lhHandle,pvInfo);

Parameters 

lhHandle (LHANDLE) - specifies the handle to query. 

pvInfo (PVOID) - points to a handle-specific structure to be initialized.  On 
return, this points to the initialized structure. 

Returns 

This function returns TRUE if the function is successful, or FALSE otherwise. 

Notes 

What pvInfo points to depends on the type of the handle specified: 

Handle type Buffer type 

HCCCONNECT pvInfo should point to a CCCONNECTINFO structure 

HCLLIST   pvInfo should point to a CLLISTINFO structure 

HCMMEM    pvInfo should point to a CMMEMINFO structure 

HCOOBJECT pvInfo should point to a COOBJECTINFO structure 

HCSSET    pvInfo should point to a CSSETINFO structure 

Related information 

o CCCONNECTINFO data type 
o CLLISTINFO data type 
o CMMEMINFO data type 
o COOBJECTINFO data type 
o CSSETINFO data type 
o CmnQueryHandle 
o CmnSetHandleInfo 


═══ 3.3. CmnQueryVersion ═══

CmnQueryVersion 

Purpose 

This function returns the major, minor, and revision numbers of the library. 

Syntax 

(VOID)CmnQueryVersion(pusMajor,pusMinor,pusRev);

Parameters 

pusMajor (PUSHORT) - points to the variable to receive the major version number 

pusMinor (PUSHORT) - points to the variable to receive the minor version number 

pusRev (PUSHORT) - points to the variable to receive the revision version 
number 


═══ 3.4. CmnSetHandleInfo ═══

CmnSetHandleInfo 

Purpose 

This function sets certain attributes about the specified handle. 

Syntax 

(BOOL)CmnSetHandleInfo(lhHandle,pvInfo);

Parameters 

lhHandle (LHANDLE) - specifies the handle to query. 

pvInfo (PVOID) - points to a handle-specific structure containing the 
information to set. 

Returns 

This function returns TRUE if the function is successful, or FALSE otherwise. 

Notes 

What pvInfo points to depends on the type of the handle specified: 

Handle type Buffer type 

HCCCONNECT pvInfo should point to a CCCONNECTINFO structure 

Related information 

o CCCONNECTINFO data type 
o CmnQueryHandle 
o CmnQueryHandleInfo 


═══ 4. Buffer routines ═══

The purpose of this group is to provide functionality that modifies entire 
buffers which can be comprised of any type of data.  This group could 
eventually be expanded to provide a text buffer engine to be used in building 
editor applications. 

Listed below are the functions which comprise this group: 

o CmnBufCompressBytes 
o CmnBufDecompressBytes 
o CmnBufDecryptBytes 
o CmnBufEncryptBytes 


═══ 4.1. CmnBufCompressBytes ═══

CmnBufCompressBytes 

Purpose 

This function attempts to compress the contents of a buffer. 

Syntax 

(BOOL)CmnBufCompressBytes(pbInBuf,ulSzInBuf,pbOutBuf,pulSzOutBuf);

Parameters 

pbInBuf (PBYTE) - points to the buffer containing the data to be compressed. 

ulSzInBuf (ULONG) - specifies the size of the buffer pointed to by pbInBuf. 

pbOutBuf (PBYTE) - points to the buffer to hold the compressed data. 

pulSzOutBuf (PULONG) - points to the variable specifying the size of the buffer 
pointed to by pbOutBuf.  On return, the variable contains the size of the 
compressed data. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

CmnBufCompressBytes uses a run-length-encoding algorithm when compressing the 
data.  While this algorithm is not expensive in CPU time consumed, it is not 
very good at compressing either and it is not guaranteed that the size of the 
compressed data will be less than the size of the original data. 

If you specify NULL for pbOutBuf, no data is written, but pulSzOutBuf will 
still be updated; so, you could specify NULL first to determine the size of the 
buffer needed before actually compressing the data. 

Related information 

o CmnBufDecompressBytes 


═══ 4.2. CmnBufDecompressBytes ═══

CmnBufDecompressBytes 

Purpose 

This function decompresses the contents of a buffer which was compressed 
previously using CmnBufCompressBytes. 

Syntax 

(BOOL) CmnBufDecompressBytes(pbInBuf,ulSzInBuf,pbOutBuf,pulSzOutBuf);

Parameters 

pbInBuf (PBYTE) - points to the buffer containing the data to be decompressed. 

ulSzInBuf (ULONG) - specifies the size of the buffer pointed to by pbInBuf. 

pbOutBuf (PBYTE) - points to the buffer to hold the decompressed data. 

pulSzOutBuf (PULONG) - points to the variable specifying the size of the buffer 
pointed to by pbOutBuf.  On return, the variable contains the size of the 
decompressed data. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

There is no error checking to insure that the buffer was compressed with 
CmnBufCompressBytes.  This responsibility is left to the application designer. 

Related information 

o CmnBufCompressBytes 


═══ 4.3. CmnBufDecryptBytes ═══

CmnBufDecryptBytes 

Purpose 

This function decrypts the contents of a buffer which was encrypted previously 
using CmnBufEncryptBytes. 

Syntax 

(BOOL)CmnBufDecryptBytes(pbInBuf,ulSzBuf,pbOutBuf);

Parameters 

pbInBuf (PBYTE) - points to the buffer containing the data to be decrypted. 

ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pbInBuf. 

pbOutBuf (PBYTE) - points to the buffer to contain the decrypted data. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

There is no error checking to insure that the buffer was encrypted with 
CmnBufEncryptBytes.  This responsibility is left to the application designer. 

Related information 

o CmnBufEncryptBytes 


═══ 4.4. CmnBufEncryptBytes ═══

CmnBufEncryptBytes 

Purpose 

This function encrypts a buffer using the NSS algorithm. 

Syntax 

(BOOL)CmnBufEncryptBytes(pbInBuf,ulSzBuf,pbOutBuf);

Parameters 

pbInBuf (PBYTE) - points to the buffer containing the data to be encrypted. 

ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pbInBuf. 

pbOutBuf (PBYTE) - points to the buffer to contain the encrypted data. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

NSS is an acronym for not-so-secure and describes the strength of the algorithm 
used.  The encrypted data is always of the same length as the original data. 
It is suggested that this function be used in conjunction with the function 
CmnBufCompressBytes to result in data that will not so easily be decyphered. 

Related information 

o CmnBufDecryptBytes 


═══ 5. Communication routines ═══

The purpose of this group is to provide easy to use communication routines for 
client/server application development.  The bidirectional connections are 
implemented via named pipes and can thus work locally or over a LAN. 

A client simply opens a connection and starts reading and/or writing to it, 
while a server waits for a connection and reads/writes to a private connection 
which is derived from the "control connection" (see the pseudocode below). This 
yields three connection types: 

 1. Client 
 2. Server 
 3. Server-connect 

/* Client */
HCCCONNECT hccConnect;

CmnComOpenConnection(...,&hccConnect);
CmnComReadData(hccConnect,...);
CmnComWriteData(hccConnect,...);
CmnComSendControl(hccConnect,CSC_CTRL_CLOSE);
CmnComCloseConnection(&hccConnect);
/* ------------------------------------------------ */
/* Server */
HCCCONNECT hccServer;
HCCCONNECT hccConnect;

CmnComOpenConnection(...,&hccServer);

CmnComWaitConnection(hccServer,&hccConnect);
/****************************************************/
/* For peer-to-peer, we would close hccServer after */
/* establishing a data connection with a client     */
/****************************************************/
CmnComReadData(hccConnect,...);
CmnComWriteData(hccConnect,...);
CmnComSendControl(hccConnect,CSC_CLOSE);
CmnComCloseConnection(&hccServer);

CmnComCloseConnection(&hccConnect);

Using this implementation strategy has two advantages:  1) it is very easy to 
create client/server or peer-to-peer applications and 2) programmers familiar 
with TCP/IP will find this very familiar. 

Data is written in the form of packets, allowing for a handshaking protocol to 
be used by the functions.  This insures that the other end receives the data 
written into the connection. 

Listed below are the functions which comprise this group: 

o CmnComCloseConnection 
o CmnComOpenConnection 
o CmnComQueryData 
o CmnComReadData 
o CmnComSendControl 
o CmnComWaitConnection 
o CmnComWriteData 


═══ 5.1. CmnComCloseConnection ═══

CmnComCloseConnection 

Purpose 

Closes a connection. 

Syntax 

(COMERROR)CmnComCloseConnection(phccConnect)

Parameters 

phccConnect (PHCCCONNECT) - points to the variable specifying the handle of the 
connection.  On return, this variable contains NULL. 

Returns 

This function returns one of the following values: 

COM_ERR_NOERROR 
COM_ERR_BADHANDLE 

Notes 

Use CmnComCloseConnection to close a specific connection.  Note that closing a 
server connection does not close any private data connections that were 
established from the server connection. 

It is recommended to send a CSC_CLOSE control code to indicate to the 
application on the other side that the connection is about to be closed. 

Related information 

o HCCCONNECT data type 
o CmnComOpenConnection 
o CmnComSendControl 


═══ 5.2. CmnComOpenConnection ═══

CmnComOpenConnection 

Purpose 

Creates a new connection handle based upon the information provided. 

Syntax 

(COMERROR)CmnComOpenConnection(pcoiInfo,phccConnect)

Parameters 

pcoiInfo (PCCOPENINFO) - points to a CCOPENINFO structure which describes the 
connection to be created.  This parameter is required.  On return, the usAttr 
field specifies the type of connection that was established (e.g. client, 
server, or server-connect). 

phccConnect (PHCCCONNECT) - points to the variable which receives the new 
connection handle. 

Returns 

This function returns one of the following values: 

COM_ERR_NOERROR 
COM_ERR_BADARGUMENT 
COM_ERR_CC_CLOSE 
COM_ERR_CC_RESET 
COM_ERR_ERROR 
COM_ERR_INITFAILED 
COM_ERR_NOCONNECTION 
COM_ERR_NOMEMORY 
COM_ERR_READFAILED 
COM_ERR_TIMEOUT 

Notes 

Use CmnComOpenConnection to create a new connection.  If the achMachine field 
of the CCOPENINFO structure is empty, then the connection is a local one.  Note 
that the timeout value (the lTimeout field) is changeable via CmnSetHandleInfo. 
This allows you to set a timeout now until a connection is established and then 
change it later for data retrieval. 

Server connections cannot be read from or written to.  Instead, they are used 
to call CmnComWaitConnection to establish a server-connect connection for data 
transfer. 

Related information 

o CCOPENINFO data type 
o HCCCONNECT data type 
o CmnComCloseConnection 
o CmnComWaitConnection 


═══ 5.3. CmnComQueryData ═══

CmnComQueryData 

Purpose 

Checks to see if data is available for reading. 

Syntax 

(COMERROR)CmnComQueryData(hccConnect,pulData)

Parameters 

hccConnect (HCCCONNECT) - specifies the connection handle. 

pulData (PULONG) - points to the variable which receives the number of bytes 
available. 

Returns 

This function returns one of the following values: 

COM_ERR_NOERROR 
COM_ERR_BADHANDLE 

Notes 

Use CmnComQueryData to determine if data is available on the connection for 
reading.  Note that if the application writes data to the connection and the 
receiving end does not read the data before this function is called, pusData 
will return 0 bytes available. 

Related information 

o HCCCONNECT data type 
o CmnComReadData 
o CmnComWriteData 


═══ 5.4. CmnComReadData ═══

CmnComReadData 

Purpose 

Reads data from a connection and sends an acknowledgement to the other end of 
the connection. 

Syntax 

(COMERROR)CmnComReadData(hccConnect,pvBuf,pulSzBuf)

Parameters 

hccConnect (HCCCONNECT) - specifies the connection handle. 

pvBuf (PVOID) - points to the buffer to receive the data. 

pulSzBuf (PULONG) - points to the variable specifying the size of the buffer 
pointed to by pvBuf.  On return, this variable contains the number of bytes 
actually read from the connection. 

Returns 

This function returns one of the following values: 

COM_ERR_NOERROR 
COM_ERR_BADDATA 
COM_ERR_BADHANDLE 
COM_ERR_BUFFERTOOLARGE 
COM_ERR_CC_CLOSE 
COM_ERR_CC_RESET 
COM_ERR_ERROR 
COM_ERR_INITFAILED 
COM_ERR_READFAILED 
COM_ERR_TIMEOUT 

Notes 

Use CmnComReadData to read data from a connection.  Note that if the buffer 
specified is not large enough to contain the data in the current packet, the 
additional bytes are discarded.  Thus, if a predetermined, fixed data length is 
not used, it is highly recommended that CmnComQueryData is called to retrieve 
the size of the current packet.  If there is no data at the front of the 
connection for the application to read, this function waits until there is data 
or until a timeout occurs. 

For 16-bit applications, there is a limit of 61440 bytes that can be read in 
one call. 

Note that if the other end sends a control code, no data is placed into pvBuf 
but the appropriate COM_ERR_CC_* code is returned instead. 

Related information 

o HCCCONNECT data type 
o CmnComQueryData 
o CmnComSendControl 
o CmnComWriteData 


═══ 5.5. CmnComSendControl ═══

CmnComSendControl 

Purpose 

This function sends a control code to the other end of the connection. 

Syntax 

(COMERROR)CmnComSendControl(hccConnect,ulCtrlCode)

Parameters 

hccConnect (HCCCONNECT) - specifies the connection handle. 

ulCtrlCode (ULONG) - specifies a CSC_* control code. 

Returns 

This function returns one of the following values: 

COM_ERR_NOERROR 
COM_ERR_BADACK 
COM_ERR_BADCONTROL 
COM_ERR_BADHANDLE 
COM_ERR_NOTIMPLEMENTED 
COM_ERR_WRITEFAILED 

Notes 

Use CmnComSendControl to send a control code to the other end of the 
connection.  "Control codes" are predefined data packets which indicate that a 
particular action is to be performed.  For CSC_CLOSE control codes, it is 
conceivable that the other end of the connection is able to close the 
connection before the packet acknowledgement is read by this end.  Thus, a 
return value of COM_ERR_BADACK should be accounted for in your application 
code. It is highly recommended that a CSC_CLOSE control code is sent before 
closing the connection to allow the other end to perform any necessary cleanup 
(such as reading any data that is expected). 

Note that this function unconditionally waits for an acknowledgement. 

Related information 

o CSC_ constants 
o HCCCONNECT data type 


═══ 5.6. CmnComWaitConnection ═══

CmnComWaitConnection 

Purpose 

Waits for a connection from a client. 

Syntax 

(COMERROR)CmnComWaitConnection(hccServer,phccConnect)

Parameters 

hccServer (HCCCONNECT) - specifies the server connection handle. 

phccConnect (PHCCCONNECT) - points to the variable which receives the created 
server-connect connection handle. 

Returns 

This function returns one of the following values: 

COM_ERR_NOERROR 
COM_ERR_BADHANDLE 
COM_ERR_ERROR 
COM_ERR_INITFAILED 
COM_ERR_NOMEMORY 
COM_ERR_NONEFREE 
COM_ERR_NOTSERVER 
COM_ERR_TIMEOUT 
COM_ERR_WRITEFAILED 

Notes 

Use CmnComWaitConnection to listen for a connection by a client. When this 
happens, a server-connect connection is created for data exchange between the 
applications.  This allows the hccServer handle to continue to listen for other 
connections via subsequent calls to this function.  If peer-to-peer 
communications are desired, CmnComCloseConnection can be called to close the 
server connection so that no further data connections are established. 

A server may have up to 256 associated server-connect connections spawned from 
it, but this may exceed a system-imposed limit. 

Related information 

o HCCCONNECT data type 
o CmnComCloseConnection 


═══ 5.7. CmnComWriteData ═══

CmnComWriteData 

Purpose 

Writes data to a connection and waits for an acknowledgement from the other end 
of the connection. 

Syntax 

(COMERROR)CmnComWriteData(hccConnect,pvBuf,ulSzBuf)

Parameters 

hccConnect (HCCCONNECT) - specifies the connection handle. 

pvBuf (PVOID) - points to the buffer containing the data to write. 

ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pvBuf. 

Returns 

This function returns one of the following values: 

COM_ERR_NOERROR 
COM_ERR_BADACK 
COM_ERR_BADHANDLE 
COM_ERR_BUFFERTOOLARGE 
COM_ERR_WRITEFAILED 

Notes 

Use CmnComWriteData to write data to a connection. Acknowledgement receipt is 
handled transparently by the function. 

For 16-bit applications, there is a limit of 61440 bytes that can be written in 
one call. 

Related information 

o HCCCONNECT data type 
o CmnComReadData 


═══ 6. Debugging routines ═══

The purpose of this group is to provide aid in debugging your applications. 
While they are not anything spectacular, I have found them helpful from time to 
time. 

Listed below are the functions which comprise this group: 

o CmnDbgWriteBinary 
o CmnDbgWriteRecord 
o CmnDbgWriteText 


═══ 6.1. CmnDbgWriteBinary ═══

CmnDbgWriteBinary 

Purpose 

This function writes the contents of a buffer to a file. 

Syntax 

(SHORT)CmnDbgWriteBinary(pvFile,
                         usFileType,
                         pvBuf,
                         usSzBuf);

Parameters 

pvFile (PVOID) - points to either the file name or a FILE structure (as defined 
in <stdio.h>). 

usFileType (USHORT) - specifies a DWT_TYPE_ constant describing the contents of 
pvFile. 

pvBuf (PVOID) - points to the buffer to be written. 

usSzBuf (USHORT) - specifies the size of the buffer pointed to by pvBuf. 

Returns 

This function returns the number of bytes successfully written, or DWT_ERROR 
otherwise. 

Notes 

Use CmnDbgWriteBinary to write the contents of a buffer to a specific file. 
The format of the output is a combination of hexadecimal on the left side with 
ASCII representation on the right with a vertical line separating the two. 
Unprintable characters (as defined by the function isprint) are displayed as 
periods in the ASCII output. 

Related information 

o DWT_TYPE_ constants 
o CmnDbgWriteText 


═══ 6.2. CmnDbgWriteRecord ═══

CmnDbgWriteRecord 

Purpose 

This function writes the contents of a structure to a file. 

Syntax 

(SHORT)CmnDbgWriteRecord(pvFile,
                         usFileType,
                         pcFormat,
                         usNumRecs,
                         pbBuf);

Parameters 

pvFile (PVOID) - points to either the file name or a FILE structure (as defined 
in <stdio.h>). 

usFileType (USHORT) - specifies a DWT_TYPE_ constant describing the contents of 
pvFile. 

pcFormat (PCSLINEDESC) - points to an array of CSLINEDESC structures describing 
the format of the structure to be written. 

usNumRecs (USHORT) - specifies the number of records pointed to by pcFormat. 

pbBuf (PBYTE) - points to the structure to write. 

Returns 

This function returns the number of fields in the structure successfully 
written, or DWT_ERROR otherwise. 

Notes 

Use CmnDbgWriteRecord to write the contents of a record to a specific file. 
This function calls CmnDbgWriteText to actually write the results, so the file 
is guaranteed to be flushed after every field is output. 

Related information 

o DWT_TYPE_ constants 
o CSLINEDESC data type 
o CmnDbgWriteText 


═══ 6.3. CmnDbgWriteText ═══

CmnDbgWriteText 

Purpose 

This function writes text to a specified file. 

Syntax 

(SHORT)CmnDbgWriteText(pvFile,usFileType,pchFmt,...);

Parameters 

pvFile (PVOID) - points to either the file name or a FILE structure (as defined 
in <stdio.h>). 

usFileType (USHORT) - specifies a DWT_TYPE_ constant describing the contents of 
pvFile. 

pchFmt (PCHAR) - points to the format string (as in the C printf routine). 

... (va_list) - specifies any additional arguments referred to by pchFmt 

Returns 

This function returns the number of characters successfully written, or 
DWT_ERROR otherwise. 

Notes 

Use CmnDbgWriteText to write information to a file.  By specifying 
DWT_TYPE_FILE for usFileType, you can use a predefined stream (stdout, stderr) 
or any other file that is already opened. Specifying DWT_TYPE_NAME indicates 
that this function should open the file in append mode and close it before 
returning. 

o DWT_TYPE_ constants 


═══ 7. File routines ═══

The purpose of this group is to provide functions which help you perform common 
tasks without a lot of the work. 

Listed below are the functions which comprise this group: 

o CmnFilCopyDiskette 
o CmnFilCreateSearch 
o CmnFilDestroySearch 
o CmnFilFormatDiskette 
o CmnFilInstallDiskette 
o CmnFilQueryExtAttribute 
o CmnFilQueryLabel 
o CmnFilSearchFiles 
o CmnFilSetExtAttribute 
o CmnFilSplitFilename 


═══ 7.1. CmnFilCopyDiskette ═══

CmnFilCopyDiskette 

Purpose 

This function copies the contents of a diskette onto another diskette. 

Syntax 

(BOOL)CmnFilCopyDiskette(chSrc,chDest,ulOptions,pfnCallback,pvUser);

Parameters 

chSrc (CHAR) - specifies the source drive and can be upper- or lower-case. 

chDest (CHAR) - specifies the destination drive and can be upper- or 
lower-case. 

ulOptions (ULONG) - one or more FCD_OPT_* constants controlling the behavior of 
this function. 

pfnCallback (PFNDISKIO) - points to a callback function.  See below for more 
information. 

pvUser (PVOID) - pointer to user data which is passed to pfnCallback. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnFilCopyDiskette to copy one diskette onto another.  The power of this 
function is in the use of pfnCallback; this callback function is called by 
CmnFilCopyDiskette in various times for various reasons.  See the items listed 
below for more information on the specifics of each constant. 

Related information 

o FCD_TYPE_ constants 
o FCD_MSG_ constants 
o FCD_ERR_ constants 
o PFNDISKIO function 


═══ 7.2. CmnFilCreateSearch ═══

CmnFilCreateSearch 

Purpose 

This function creates a search handle for use in subsequent calls to 
CmnFilSearchFiles. 

Syntax 

(BOOL)CmnFilCreateSearch(pchMask,ulAttr,phcSearch);

Parameters 

pchMask (PCHAR) - points to the file mask to be used when searching for the 
files. 

ulAttr (ULONG) - specifies a combination of FCS_ATTR_ constants which specify 
the types of files to search for. 

phcSearch (PHCFSEARCH) - on return, this points to the variable containing the 
created search handle. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnFilCreateSearch to create a search handle for use in calls to 
CmnFilSearchFiles.  Note that, unlike DosFindFirst, "normal" files (those with 
no special attributes) are not searched for unless FCS_ATTR_NORMAL is specified 
in ulAttr. 

Related information 

o FCS_ATTR_ constants 
o HCFSEARCH data type 
o CmnFilSearchFiles 


═══ 7.3. CmnFilDestroySearch ═══

CmnFilDestroySearch 

Purpose 

This function destroys a search handle created by CmnFilCreateSearch. 

Syntax 

(BOOL)CmnFilDestroySearch(hcSearch);

Parameters 

phcSearch (PHCFSEARCH) - points to the variable specifying the search handle to 
destroy.  On return, this variable contains NULL. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnFilDestroySearch to free any resources consumed by the search functions. 

Related information 

o HCFSEARCH data type 
o CmnFilCreateSearch 


═══ 7.4. CmnFilFormatDiskette ═══

CmnFilFormatDiskette 

Purpose 

This function formats a diskette. 

Syntax 

(BOOL)CmnFilFormatDiskette(chDrive,pfiInfo,pfnCallback,pvUser);

Parameters 

chDrive (CHAR) - specifies the drive in which the diskette to be formatted is 
placed. 

pfiInfo (PCFFORMATINFO) - points to a CFFORMATINFO structure specifying the 
format parameters to be used.  If NULL the parameters for the diskette are used 
(if the diskette is already formatted), or the defaults for the drive are used 
(if the diskette is not already formatted). 

pfnCallback (PFNDISKIO) - points to a callback function.  See below for more 
information. 

pvUser (PVOID) - pointer to user data which is passed to pfnCallback. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnFilFormatDiskette to format a diskette.  The power of this function is 
in the use of pfnCallback; this callback function is called by 
CmnFilFormatDiskette in various times for various reasons.  See the items 
listed below for more information on the specifics of each constant. 

The boot sector that is written to the diskette consists of a program at offset 
0x40 (which is jumped to by the first two bytes of the boot sector), which 
loads and displays an ASCIIZ string beginning at offset 0x80.  The default 
message placed there is a NULL-string.  To specify your own string to be 
displayed, you need to read track 0, head 0, sector 0, and copy your string 
into the buffer containing the sector's data at the correct offset, and then 
write the new contents to track 0, head 0, sector 0. 

When determining the string to be written, be aware that - on the rarely found 
machines with single-head, single-density floppy drives - you only have 30 
bytes (including the terminating 0) for the string's contents. 

Related information 

o FCD_TYPE_ constants 
o FCD_MSG_ constants 
o FCD_ERR_ constants 
o CFFORMATINFO data type 
o PFNDISKIO function 


═══ 7.5. CmnFilInstallDiskette ═══

CmnFilInstallDiskette 

Purpose 

This function performs operations with respect to an installation diskette for 
an application. 

Syntax 

(ULONG)CmnFilInstallDiskette(pchFile,
                             pchVendor,
                             pchApp,
                             pchName,
                             pulNumLicenses,
                             ulRequest);

Parameters 

pchFile (PCHAR) - points to the name of the file to contain the installation 
data. 

pchVendor (PCHAR) - points to the name of the vendor of the application. 

pchApp (PCHAR) - points to the name of the application. 

pchName (PCHAR) - points to an arbitrary name for the installation data. 

pulNumLicenses (PULONG) - points to a variable specifying the number of 
licenses.  See below. 

ulRequest (ULONG) - specifies a function to be performed. 

Returns 

CFID_ERR_NOERROR if successful, a CFID_ERR_* constant otherwise. 

Notes 

Use CmnFilInstallDiskette to perform installation verification and other 
related functions.  The function to be performed is specified in ulRequest and 
can be one of the following: 

CFID_REQ_CREATE     Initializes the file whose name is specified in pchFile to 
                    contain a specific number of licenses. 
CFID_REQ_DECREMENT  Decrements the number of available licenses. 
CFID_REQ_INCREMENT  Increments the number of available licenses. 
CFID_REQ_QUERY      Returns the number of available licenses. 

For CFID_REQ_CREATE, pulNumLicenses should be initialized to specify the total 
number of licenses for the application.  For the other functions, the value is 
ignored.  For all functions, this variable contains the updated number of 
available licenses on return. 


═══ 7.6. CmnFilQueryExtAttribute ═══

CmnFilQueryExtAttribute 

Purpose 

This function queries the value of an extended attribute written by 
CmnFilSetExtAttribute. 

Syntax 

(BOOL)CmnFilQueryExtAttribute(pchFile,
                              pchVendor,
                              pchAppl,
                              pchName,
                              pusAttr,
                              pbValue,
                              pusSzValue);

Parameters 

pchFile (PCHAR) - points to the name of the file containing the extended 
attributes to query. 

pchVendor (PCHAR) - points to the name of the vendor whose application wrote 
the extended attribute or an FEA_ constant. 

pchAppl (PCHAR) - points to the name of the application which wrote the 
extended attribute. 

pchName (PCHAR) - points to the name of the extended attribute. 

pusAttr (PUSHORT) - points to the attribute of the extended attribute. 

pbValue (PBYTE) - points to a buffer to receive the results. On return, the 
buffer contains the value of the extended attribute. 

pusSzValue (PUSHORT) - points to a variable specifying the size of pbValue.  On 
return, this points to the number of bytes copied to the buffer. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnFilQueryExtAttribute to query an extended attribute of a file.  Because 
this call (and CmnFilSetExtAttribute) enforces the convention stated in the IBM 
Programming Toolkit's "Programming Guide", this function is only guaranteed to 
return meaningful results if the extended attribute was originally written by 
CmnFilSetExtAttribute. 

If an FEA_ constant is specified for pchVendor, pchAppl and pchName are 
ignored. 

Related information 

o FEA_ constants 
o CmnFilSetExtAttribute 


═══ 7.7. CmnFilQueryLabel ═══

CmnFilQueryLabel 

Purpose 

This function returns the label on the diskette in the specified drive. 

Syntax 

(BOOL)CmnFilQueryLabel(chDrive,pchLabel);

Parameters 

chDrive (CHAR) - specifies the drive to query. 

pchLabel (PCHAR) - points to the buffer to hold the label.  On return, this 
buffer holds the diskette label if successful. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnFilQueryLabel to determine the label of the diskette in the specified 
drive.  This function will not cause a "hard error" popup to appear if no 
diskette is in the drive; instead, this function will return FALSE. 


═══ 7.8. CmnFilSearchFiles ═══

CmnFilSearchFiles 

Purpose 

This function returns the next file found that has the characteristics 
specified when the search handle was created. 

Syntax 

(LONG)CmnFilSearchFiles(hcSearch,pchBuf,ulSzBuf);

Parameters 

hcSearch (HCFSEARCH) - specifies the search handle. 

pchBuf (PCHAR) - points to a buffer to receive the results.  On return, the 
buffer contains the fully qualified name of the next file found. 

ulSzBuf (ULONG) - specifies the size of pchBuf. 

Returns 

This function returns the attribute of the file found as a combination of 
FCS_ATTR_ constants if successful, FSF_NOFILES if no more files were found that 
match the criteria, or FSF_ERROR if an error occurred. 

Notes 

Use CmnFilSearchFiles to search for the next file that exactly matches the 
criteria (file mask and attribute) specified in the search handle. Note that 
the attribute match must be exact (i.e. not a subset).  For example, if file 
"A" has the archive, hidden, system, and read-only attributes set, it will not 
be found unless you specify all four of its attributes. 

Related information 

o FCS_ATTR_ constants 
o HCFSEARCH data type 
o CmnFilCreateSearch 


═══ 7.9. CmnFilSetExtAttribute ═══

CmnFilSetExtAttribute 

Purpose 

This function writes an extended attribute to the specified file. 

Syntax 

(BOOL)CmnFilSetExtAttribute(pchFile,
                            usAttr,
                            pchVendor,
                            pchAppl,
                            pchName,
                            pbValue,
                            usSzValue);

Parameters 

pchFile (PCHAR) - points to the name of the file containing the extended 
attributes to set. 

usAttr (USHORT) - points to the attribute of the extended attribute. 

pchVendor (PCHAR) - points to the name of the vendor whose application is 
writing the extended attribute or an FEA_ constant. 

pchAppl (PCHAR) - points to the name of the application which is writing the 
extended attribute. 

pchName (PCHAR) - points to the name of the extended attribute. 

pbValue (PBYTE) - points to a buffer containing the value of the extended 
attribute. 

usSzValue (USHORT) - specifies the size of pbValue. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnFilSetExtAttribute to write an extended attribute to a file.  Since this 
function enforces the convention stated in the IBM Programming Toolkit's 
"Programming Guide", you should use CmnFilQueryExtAttribute to read the 
extended attribute when needed or insure that the code is aware of the added 
information written. 

Related information 

If an FEA_ constant is specified for pchVendor, pchAppl and pchName are 
ignored. 

o FEA_ constants 
o CmnFilQueryExtAttribute 


═══ 7.10. CmnFilSplitFilename ═══

CmnFilSplitFilename 

Purpose 

This function splits a filename into its various components. 

Syntax 

(BOOL)CmnFilSplitFilename(pchFile,pchDrive,pchPath,pchName);

Parameters 

pchFile (PCHAR) - points to the name of the file to be split 

pchDrive (PCHAR) - points to the buffer to receive the drive 

pchPath (PCHAR) - points to the buffer to receive the path 

pchName (PCHAR) - points to the buffer to receive the name 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

pchDrive, pchPath, or pchName can be NULL if you are not interested in that 
component. 

pchDrive will always end in a colon (':'). 

pchPath will always end with a backslash ('\'). 


═══ 8. Link-list routines ═══

The purpose of this group is to provide a complete linked list implementation 
which is limited only by the amount of memory in your system. I have defined a 
list to be a set of homogeneous items; thus, each item in the list is of a 
fixed size, which is declared when the list is created.  Also, each item is 
doubly linked to provide quick access to any record from anywhere in the list. 
While this imposes an extra four bytes per record, the performance gains 
outweigh the additional memory required. 

Note that the links are hidden from the record; this is good in that if you 
want to have a list of integers, you do not have to define a structure to hold 
the integer and the links.  Additionally, this hides the implementation of the 
list from the developer, so if it changes (and it has before) the developer 
does not need to do anything other than recompile. 

Listed below are the functions which comprise this group: 

o CmnLstAddRecord 
o CmnLstAddUniqueRecord 
o CmnLstCopyList 
o CmnLstCreateList 
o CmnLstDeleteList 
o CmnLstDeleteRecord 
o CmnLstDestroyList 
o CmnLstMoveRecord 
o CmnLstPruneList 
o CmnLstQueryRecord 
o CmnLstQueryRecordCount 
o CmnLstQueryRelative 
o CmnLstQuickSortList 
o CmnLstSearchRecord 
o CmnLstSortList 
o CmnLstTraverseList 


═══ 8.1. CmnLstAddRecord ═══

CmnLstAddRecord 

Purpose 

This function adds a record to a linked list. 

Syntax 

(BOOL)CmnLstAddRecord(hclList,pvRecord,pfnSort,ppvResult,pvData);

Parameters 

hclList (HCLLIST) - handle of the linked list to add to. 

pvRecord (PVOID) - points to the record to add. 

pfnSort (PFNRECCOMP) - points to the function which defines the sort order or 
an LAR_ constant. 

ppvResult (PVOID *) - points to the variable which receives the pointer to the 
inserted record.  This can be NULL. 

pvData (PVOID) - points to application defined data which is passed to pfnSort 
as the third parameter. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnLstAddRecord to add a record to a linked list in the order defined by 
pfnSort.  Since the linked list routines maintain their own copy of the 
records, ppvResult can optionally be specified to receive the pointer to the 
record within the list. pfnSort either points to a function which defines the 
placement of the record within the list or specifies an LAR_ constant. 

Note that if uniqueness must be enforced, you should instead use 
CmnLstAddUniqueRecord. 

Related information 

o LAR_ constants 
o HCLLIST data type 
o PFNRECCOMP function 
o CmnLstAddUniqueRecord 


═══ 8.2. CmnLstAddUniqueRecord ═══

CmnLstAddUniqueRecord 

Purpose 

This function adds a record to a linked list only if it did not exist 
previously. 

Syntax 

(USHORT)CmnLstAddUniqueRecord(hclList,
                              pvRecord,
                              pfnSearch,
                              pfnSort,
                              ppvResult,
                              pvData);

Parameters 

hclList (HCLLIST) - handle of the linked list to add to. 

pvRecord (PVOID) - points to the record to add. 

pfnSearch (PFNRECCOMP) - points to the function which determines the equality 
of two records. 

pfnSort (PFNRECCOMP) - points to the function which defines the sort order. 

ppvResult (PVOID *) - points to the variable which receives the pointer to the 
inserted record.  This can be NULL. 

pvData (PVOID) - points to application defined data which is passed to 
pfnSearch and pfnSort as the third parameter. 

Returns 

This function returns LAUR_NOERROR if successful, LAUR_EXISTS if the record 
existed in the list prior to this call, or LAUR_ERROR if an error occurred. 

Notes 

Use CmnLstAddUniqueRecord to add a record in a linked list, while guaranteeing 
uniqueness within the list.  Since the linked list routines maintain their own 
copy of the records, ppvResult can optionally be specified to receive the 
pointer to the record within the list. pfnSort either points to a function 
which defines the placement of the record within the list or specifies an LAR_ 
constant. pnfSearch points to a function which determines whether or not two 
records are equal and is required. 

Related information 

o LAR_ constants 
o HCLLIST data type 
o PFNRECCOMP function 


═══ 8.3. CmnLstCopyList ═══

CmnLstCopyList 

Purpose 

This function copies the contents of one list into another list. 

Syntax 

(BOOL)CmnLstCopyList(hclList,hclCopy,pfnSort,pvData);

Parameters 

hclList (HCLLIST) - handle of the linked list to copy to. 

hclCopy (HCLLIST) - handle of the linked list to copy from. 

pfnSort (PFNRECCOMP) - points to the function which defines the sort order. 

pvData (PVOID) - points to application defined data which is passed to pfnSort 
as the third parameter. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnLstCopyList to copy the contents of one list into another.  While this 
can be used to append a list to another, this function is frequently used to 
simply copy a list so that modifications to the original list can be recovered. 

Related information 

o HCLLIST data type 


═══ 8.4. CmnLstCreateList ═══

CmnLstCreateList 

Purpose 

This function creates a linked list handle for use in subsequent calls to the 
CmnLst functions. 

Syntax 

(BOOL)CmnLstCreateList(usSzRecord,phclList);

Parameters 

usSzRecord (USHORT) - specifies the size of each record in the linked list. 

phclList (PHCLLIST) - points to the variable which receives the created linked 
list handle. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnLstCreateList to create a linked list handle which can be used in other 
CmnLst functions.  Note that only linked lists of fixed record size are 
supported, although specifying the maximum size of any record and then storing 
the actual size in the record itself would work (albeit very 
memory-inefficient). 

Since the records do not contain the link information directly, do not specify 
this in usSzRecord. 

Related information 

o HCLLIST data type 
o CmnLstDestroyList 


═══ 8.5. CmnLstDeleteList ═══

CmnLstDeleteList 

Purpose 

This function deletes the contents of a linked list. 

Syntax 

(BOOL)CmnLstDeleteList(hclList);

Parameters 

hclList (HCLLIST) - handle of the linked list to delete. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnLstDeleteList to delete the contents of a linked list. Note that the 
list still "exists" after this call; it is simply emptied of its contents.  To 
destroy a list, use CmnLstDestroyList. 

Related information 

o HCLLIST data type 
o CmnLstDestroyList 


═══ 8.6. CmnLstDeleteRecord ═══

CmnLstDeleteRecord 

Purpose 

This function deletes a record from a linked list. 

Syntax 

(BOOL)CmnLstDeleteRecord(hclList,pvRecord);

Parameters 

hclList (HCLLIST) - handle of the linked list to delete from. 

pvRecord (PVOID) - points to the record to delete. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnLstDeleteRecord to delete a specific record from a linked list.  This 
function adjusts the links in the list and frees the memory consumed by the 
record (but does not free any memory which is pointed to by any fields in the 
record).  To delete the entire list, use CmnLstDeleteList. 

Related information 

o HCLLIST data type 
o CmnLstDeleteList 


═══ 8.7. CmnLstDestroyList ═══

CmnLstDestroyList 

Purpose 

This function deletes the contents of a linked list and destroys the handle to 
the linked list. 

Syntax 

(BOOL)CmnLstDestroyList(phclList);

Parameters 

phclList (PHCLLIST) - points to the variable specifying the handle of the 
linked list to delete.  On return, this variable contains NULL. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnLstDestroyList to destroy a linked list handle.  All records are delete 
via a call to CmnLstDeleteList before destroying the handle. 

Related information 

o HCLLIST data type 
o CmnLstCreateList 
o CmnLstDeleteList 


═══ 8.8. CmnLstMoveRecord ═══

CmnLstMoveRecord 

Purpose 

This function moves a record to a position relative to another record. 

Syntax 

(BOOL)CmnLstMoveRecord(hclList,pvMove,pvWhere,sRelative);

Parameters 

hclList (HCLLIST) - handle of the linked list. 

pvMove (PVOID) - pointer to the record to move 

pvWhere (PVOID) - pointer to the record specifying the new location 

sRelative (SHORT) - either LQR_PREVIOUS or LQR_NEXT specifying immediately 
before or after pvWhere, respectively. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnLstMoveRecord to move a record before or after another record in a 
linked list. 

Related information 

o HCLLIST data type 


═══ 8.9. CmnLstPruneList ═══

CmnLstPruneList 

Purpose 

This function traverses a linked list and deletes the records that meet the 
specified criteria. 

Syntax 

(BOOL)CmnLstPruneList(hclList,pvRecord,pfnSearch,pvData);

hclList (HCLLIST) - handle of the linked list to prune. 

pvSearch (PVOID) - points to a buffer specifying the search criteria.  This is 
passed to pfnSearch as the second parameter. 

pfnSearch (PFNRECCOMP) - points to a function which determines whether or not a 
record matches the criteria. 

pvData (PVOID) - points to application defined data which is passed to 
pfnSearch as the third parameter. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnLstPruneList to remove only those records which meet a specific set of 
criteria from a linked list.  This is typically used after calling 
CmnLstCopyList to remove all but the records of interest from the copied list. 

Related information 

o HCLLIST data type 
o PFNRECCOMP function 
o CmnLstSearchRecord 


═══ 8.10. CmnLstQueryRecord ═══

CmnLstQueryRecord 

Purpose 

This function returns a pointer to the specified element in a linked list. 

Syntax 

(PVOID)CmnLstQueryRecord(hclList,sNumRecord);

Parameters 

hclList (HCLLIST) - handle of the linked list to query. 

sNumRecord (SHORT) - specifies the 0-based index of the record desired. 

Returns 

This function returns a pointer to the desired record if successful, or NULL 
otherwise. 

Notes 

Use CmnLstQueryRecord to query a specific record number from a linked list. 
Note that, if the record desired precedes or follows a previously queried 
record, it is much more efficient to instead use CmnLstQueryRelative.  This is 
an especially prominent condition in loop-based processing: 

usNumRecs=CmnLstQueryRecordCount(hclList);
for (usIndex=0; usIndex<usNumRecs; usIndex++) {
   prRecord=CmnLstQueryRecord(hclList,usIndex);
      :
} /* endfor */
should instead be coded as 

usNumRecs=CmnLstQueryRecordCount(hclList);
for (usIndex=0; usIndex<usNumRecs; usIndex++) {
   if (usIndex==0) {
      prRecord=CmnLstQueryRecord(hclList,0);
   } else {
      prRecord=CmnLstQueryRelative(prRecord,LQR_NEXT);
   } /* endif */
      :
} /* endfor */

Related information 

o HCLLIST data type 
o CmnLstQueryRelative 


═══ 8.11. CmnLstQueryRecordCount ═══

CmnLstQueryRecordCount 

Purpose 

This function queries the number of records in a linked list. 

Syntax 

(SHORT)CmnLstQueryRecordCount(hclList);

Parameters 

hclList (HCLLIST) - handle of the linked list to query. 

Returns 

This function returns the number of records in the linked list if successful, 
or LQRC_ERROR otherwise. 

Notes 

Use CmnLstQueryRecordCount to query the number of records in a linked list. 
Note that this call is expensive in terms of execution time, so it should not 
be used as the terminating condition of a loop.  Instead, store the number of 
records in a local variable prior to entering the loop and use the variable 
instead.  For example, 

for (usIndex=0; usIndex<CmnLstQueryRecordCount(hclList); usIndex++) {
   :
} /* endfor */
should instead be coded as 

usNumRecs=CmnLstQueryRecordCount(hclList);
for (usIndex=0; usIndex<usNumRecs; usIndex++) {
   :
} /* endfor */

Related information 

o HCLLIST data type 


═══ 8.12. CmnLstQueryRelative ═══

CmnLstQueryRelative 

Purpose 

This function queries either the previous or the next record from a specified 
record. 

Syntax 

(PVOID)CmnLstQueryRelative(pvRecord,sWhich);

Parameters 

pvRecord (PVOID) - points to the record to query. 

sWhich (SHORT) - specifies an LQR_ constant. 

Returns 

This function returns the relative record if successful, or NULL if the record 
prior to the head of the list or record following the tail of the list was 
specified or an error occurred. 

Notes 

Use CmnLstQueryRelative to query either the previous or the next record from a 
specified record.  While this call is very fast, it does not attempt to 
validate that the record actually belongs to any list; this responsibility is 
left to the programmer. 

Related information 

o LQR_ constants 
o HCLLIST data type 


═══ 8.13. CmnLstQuickSortList ═══

CmnLstQuickSortList 

Purpose 

This function sorts a linked list using a version of the "quick sort" algorithm 
modified for use with linked lists. 

Syntax 

(BOOL)CmnLstQuickSortList(hclList,pfnMedian,pfnCompare,pvData);

Parameters 

hclList (HCLLIST) - handle of the list to sort. 

pfnMedian (PFNRECMED) - points to the function which defines the median of the 
list. 

pfnCompare (PFNRECCOMP) - points to the function which determines whether or 
not two records are equal. 

pvData (PVOID) - points to application defined data which is passed to 
pfnMedian and pfnCompare as the third parameter. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnLstQuickSortList to quickly sort a linked list. Unfortunately, since the 
records of the linked list are rarely in a contiguous block of memory, this 
function is not as quick as would be expected, although it is much faster than 
using CmnLstSortList, which uses a bubble-sort implementation. 

This speed does not come without its downside - this function consumes a lot of 
both stack space (due to the recursive nature of the algorithm) and heap space 
(since each partition must be stored in a temporary list). 

Related information 

o HCLLIST data type 
o PFNRECMED function 
o PFNRECCOMP function 


═══ 8.14. CmnLstSearchRecord ═══

CmnLstSearchRecord 

Purpose 

This function searches a linked list for a record which matches the search 
criteria. 

Syntax 

(PVOID)CmnLstSearchRecord(pvRecord,pvSearch,pfnSearch,pvData);

Parameters 

pvRecord (PVOID) - points to the first record to begin searching with. 

pvSearch (PVOID) - points to a buffer specifying the search criteria.  This is 
passed to pfnSearch as the second parameter. 

pfnSearch (PFNRECCOMP) - points to a function which determines whether or not a 
record matches the criteria. 

pvData (PVOID) - points to application defined data which is passed to 
pfnSearch as the third parameter. 

Returns 

This function returns a pointer to the first record on or after pvRecord which 
matches the search criteria if successful, or NULL otherwise. 

Notes 

Use CmnLstSearchRecord to search a linked list for records matching specified 
search criteria.  Typically, pvSearch is simply a pointer to a record of the 
same type that comprises the linked list with the pertinet fields initialized 
to the values to be compared against every record on or after pvRecord. 
pfnSearch then compares these fields and returns the appropriate value. 

Related information 

o HCLLIST data type 
o PFNRECCOMP function 


═══ 8.15. CmnLstSortList ═══

CmnLstSortList 

Purpose 

This function sorts a linked list using a version of the "bubble" sort 
algorithm modified for use with linked lists. 

Syntax 

(BOOL)CmnLstSortList(hclList,pfnSort,pvData);

Parameters 

hclList (HCLLIST) - handle of the list to sort. 

pfnSort (PFNRECCOMP) - points to the function which determines whether or not 
two records are equal. 

pvData (PVOID) - points to application defined data which is passed to pfnSort 
as the third parameter. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnLstSortList to sort a linked list.  Although no extra resources are 
consumed (with the exception of stack space for local variables), the algorithm 
is extremely slow.  For sorts that require less time (and are not concerned 
with the consumption of resources), use CmnLstQuickSortList instead. 

Related information 

o HCLLIST data type 
o PFNRECCOMP function 
o CmnLstQuickSortList 


═══ 8.16. CmnLstTraverseList ═══

CmnLstTraverseList 

Purpose 

This function traverses a linked list. 

Syntax 

(BOOL)CmnLstTraverseList(hclList,pfnFunc,pvData);

Parameters 

hclList (HCLLIST) - handle of the list to traverse. 

pfnFunc (PFNRECFUNC) - points to a function which is called for each record in 
the linked list. 

pvData (PVOID) - points to application defined data which is passed to pfnFunc 
as the second parameter. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnLstTraverseList to traverse a linked list for debugging purposes.  For 
every record in the linked list, pfnFunc is called, giving the application the 
ability to write the contents of the record to the screen, a file, a 
communication port, etc..  When used in conjunction with CmnDbgWriteRecord, a 
linked list dump can be easily generated with minimal code. 

Related information 

o HCLLIST data type 
o PFNRECFUNC function 
o CmnDbgWriteRecord 


═══ 9. Memory allocation routines ═══

The purpose of this group is to provide memory allocation routines which are 
easy to use and provide functionality above that provided by the C run-time 
library.  The routines use the DosSubAlloc and DosSubFree kernel functions for 
the suballocation of the individual heaps, so there are no free lists that are 
maintained by these routines (less code means less bugs). 

A useful function is the CmnQueryHandleInfo function which returns the total 
amount of memory in use by a memory manager handle. 

Listed below are the functions which comprise this group: 

o CmnMemAllocate 
o CmnMemFree 
o CmnMemInitialize 
o CmnMemQueryMemSize 
o CmnMemReset 
o CmnMemTerminate 


═══ 9.1. CmnMemAllocate ═══

CmnMemAllocate 

Purpose 

This function allocates a block of memory of a specified size. 

Syntax 

(MEMERROR)CmnMemAllocate(hcmMem,ulSzBuf,ppvBuf);

Parameters 

hcmMem (HCMMEM) - handle of the memory manager instance. 

ulSzBuf (ULONG) - specifies the size of the memory block requested. 

ppvBuf (PVOID *) - points to the variable which receives the pointer to the 
allocated memory. 

Returns 

This function returns one of the following values: 

MEM_ERR_NOERROR 
MEM_ERR_BADHANDLE 
MEM_ERR_NOMEMORY 
MEM_ERR_SIZETOOLARGE 

Notes 

The algorithm used by the function is to attempt to allocate the specified 
amount of memory from those heaps which already are being used.  If the request 
cannot be satisfied and there is at least one heap slot that is not in use, 
then a new heap is created and the memory requested is allocated from the new 
heap. 

Related information 

o HCMMEM data type 
o CmnMemFree 
o CmnMemReset 


═══ 9.2. CmnMemFree ═══

CmnMemFree 

Purpose 

This function frees a block of memory previously allocated with CmnMemAllocate. 

Syntax 

(MEMERROR)CmnMemFree(hcmMem,pvBuf);

Parameters 

hcmMem (HCMMEM) - handle of the memory manager instance. 

pvBuf (PVOID) - pointer to the memory block to free 

Returns 

This function returns one of the following values: 

MEM_ERR_NOERROR 
MEM_ERR_BADHANDLE 
MEM_ERR_BADPOINTER 
MEM_ERR_ERROR 

Notes 

Because of the dynamic committal strategy used by the memory routines, a 
reference count is maintained for each heap that is in use and it is updated 
whenever either CmnMemAllocate or CmnMemFree is called. When this function 
determines that the reference count is zero, it deallocates the memory used by 
the heap and marks the heap as "empty". 

Related information 

o HCMMEM data type 
o CmnMemAllocate 
o CmnMemReset 


═══ 9.3. CmnMemInitialize ═══

CmnMemInitialize 

Purpose 

This function creates an instance of the memory manager. 

Syntax 

(MEMERROR)CmnMemInitialize(pcmiInfo,phcmMem);

Parameters 

pcmiInfo (PCMMEMINFO) - points to a CMMEMINFO structure which describes the 
desired characteristics of the instance.  If NULL, the defaults are used (see 
below). 

phcmMem (PHCMMEM) - points to the variable which receives the created instance 
of the memory manager. 

Returns 

This function returns one of the following values: 

MEM_ERR_NOERROR 
MEM_ERR_NOMEMORY 

Notes 

The heaps are subdivided by the CmnMemAllocate and CmnMemFree routines using 
the DosSubAlloc and DosSubFree APIs.  Allowing for housekeeping data kept by 
both the system and the memory manager, the amount of allocatable memory will 
be less than the value of ulSzHeaps (how much less depends on the number of 
allocations have been made from a particular heap). 

Related information 

o HCMMEM data type 
o CMMEMINFO data type 
o CmnMemReset 
o CmnMemTerminate 


═══ 9.4. CmnMemQueryMemSize ═══

CmnMemQueryMemSize 

Purpose 

This function returns the size of the specified memory block. 

Syntax 

(ULONG)CmnMemQueryMemSize(pvBuf);

Parameters 

pvBuf (PVOID) - points to a memory block previously allocated by 
CmnMemAllocate. 

Returns 

This function returns the size of the memory block specified. 

Notes 

This function does no validity checks to insure that pvBuf was indeed allocated 
with CmnMemAllocate. 

Related information 

o CmnMemAllocate 


═══ 9.5. CmnMemReset ═══

CmnMemReset 

Purpose 

This function resets the specified instance of the memory manager to its 
initial state. 

Syntax 

(MEMERROR)CmnMemReset(hcmMem);

Parameters 

hcmMem (HCMMEM) - handle of the memory manager instance. 

Returns 

This function returns one of the following values: 

MEM_ERR_NOERROR 
MEM_ERR_BADHANDLE 

Notes 

This function returns all memory to the system and reinitializes all of the 
internal heaps to the "empty" state. 

Related information 

o HCMMEM data type 
o CmnMemInitialize 
o CmnMemTerminate 


═══ 9.6. CmnMemTerminate ═══

CmnMemTerminate 

Purpose 

This function destroys the specified instance of the memory manager. 

Syntax 

(MEMERROR)CmnMemTerminate(phcmMem);

Parameters 

phcmMem (PHCMMEM) - points to the variable specifying the handle of the memory 
manager instance to destroy.  On return, this contains NULL. 

Returns 

This function returns one of the following values: 

MEM_ERR_NOERROR 
MEM_ERR_BADHANDLE 
MEM_ERR_ERROR 

Notes 

This function first calls CmnMemReset to return all allocated memory to the 
system. 

Related information 

o HCMMEM data type 
o CmnMemInitialize 
o CmnMemReset 


═══ 10. Object handling routines ═══

The purpose of this group is to provide object handling routines.  An "object" 
is an abstract concept that is defined by an application.  No structure is 
imposed on the objects except with regards to their names. Because of this, the 
APIs are limited in the functionality they can provide. 

I have hopes of modifying this group to allow for objects that are distributed 
across a network, but am not sure that I will have the time or the resources to 
fulfill this vision. 

Listed below are the functions which comprise this group: 

o CmnObjCreateObject 
o CmnObjDestroyObject 
o CmnObjInitialize 
o CmnObjObjectFromName 
o CmnObjQueryObject 
o CmnObjQueryObjectData 
o CmnObjReset 
o CmnObjSetObjectData 
o CmnObjTerminate 


═══ 10.1. CmnObjCreateObject ═══

CmnObjCreateObject 

Purpose 

This function creates a new object. 

Syntax 

(OBJERROR)CmnObjCreateObject(hcoParent,pchName,phcoResult)

Parameters 

hcoParent (HCOOBJECT) - handle of the parent object. 

pchName (PCHAR) - points to the desired subname of the object. 

phcoResult (PHCOOBJECT) - points to the variable that receives the newly 
created object handle. 

Returns 

This function returns one of the following values: 

OBJ_ERR_NOERROR 
OBJ_ERR_BADARGUMENT 
OBJ_ERR_BADHANDLE 
OBJ_ERR_BADNAME 
OBJ_ERR_INITFAILED 
OBJ_ERR_NOMEMORY 
OBJ_ERR_NOTROOT 

Notes 

Use CmnObjCreateObject to create a new object whose parent is specified by 
hcoParent.  The "subname" can contain any characters except backslashes (see 
CmnObjObjectFromName). 

Related information 

o HCOOBJECT data type 
o CmnObjDestroyObject 


═══ 10.2. CmnObjDestroyObject ═══

CmnObjDestroyObject 

Purpose 

This function destroys an object. 

Syntax 

(OBJERROR)CmnObjDestroyObject(phcoObject)

Parameters 

phcoObject (PHCOOBJECT) - points to the variable specifying the handle of the 
object to destroy.  On return, this variable contains NULL 

Returns 

This function returns one of the following values: 

OBJ_ERR_NOERROR 
OBJ_ERR_BADARGUMENT 
OBJ_ERR_BADHANDLE 
OBJ_ERR_NOMEMORY 
OBJ_ERR_NOTROOT 
OBJ_ERR_OBJECTCORRUPTED 

Notes 

Use CmnObjDestroyObject to destroy an object previously created with 
CmnObjCreateObject.  Any data (see CmnObjSetObjectData) is disposed of and the 
memory is returned to the system.  It is an error if the root object is 
specified in phcoObject. 

For objects with children, the children become adopted children of the object's 
parent. 

Related information 

o HCOOBJECT data type 
o CmnObjCreateObject 


═══ 10.3. CmnObjInitialize ═══

CmnObjInitialize 

Purpose 

This function initializes an instance of the object manager and creates the 
root object. 

Syntax 

(OBJERROR)CmnObjInitialize(pcoriInfo,phcoRoot)

Parameters 

pcoriInfo (PCOROOTINFO) - points to a COROOTINFO structure containing desired 
characteristics of the root object.  If NULL, the default values are used. 

phcoRoot (PHCOOBJECT) - points to the variable to receive the handle of the 
root object. 

Returns 

This function returns one of the following values: 

OBJ_ERR_NOERROR 
OBJ_ERR_BADNAME 
OBJ_ERR_INITFAILED 
OBJ_ERR_NOMEMORY 

Notes 

Use CmnObjInitialize to create a root object handle which can be used in 
subsequent calls to other object functions.  The achServer field of the 
COROOTINFO structure is unused at this time and could possibly disappear in the 
future. 

Related information 

o HCOOBJECT data type 
o CmnObjTerminate 


═══ 10.4. CmnObjObjectFromName ═══

CmnObjObjectFromName 

Purpose 

This function finds an object with a given name. 

Syntax 

(OBJERROR)CmnObjObjectFromName(hcoObject,pchName,phcoResult)

Parameters 

hcoObject (HCOOBJECT) - handle of the object to search from. 

pchName (PCHAR) - points to the name of the object to search for. 

phcoResult (PHCOOBJECT) - points to the variable which receives the handle of 
the object if found. 

Returns 

This function returns one of the following values: 

OBJ_ERR_NOERROR 
OBJ_ERR_BADHANDLE 
OBJ_ERR_NOTFOUND 

Notes 

The object name structure is extremely similar to the directory/filename 
structure of the file system.  Each object has a subname which, when combined 
with the subnames of its ancestors, produces a fully qualified name; each 
subname is separated by a backslash. 

pchName can specify either a name relative to the specified object, or it can 
specify an absolute name by prepending it with a backslash. Also, as with the 
file system, you can specify "." and ".." to indicate the current object and 
its parent, respectively. 

For example, if you have the following objects with the given relationships 

                        root
                        /  \
                 child1      child2
                 /  |          |  \
            child3 child4  child5 child6

the following calls return the indicated results: 

CmnObjObjectFromName(root,"child1\\child4") returns child4. 

CmnObjObjectFromName(child3,"..\\..\\child2\\child5") returns child5. 

CmnObjObjectFromName(child4,"..\\child3\\..\\child4\\..\\..") returns root. 

CmnObjObjectFromName(root,"..") returns an error. 

Related information 

o HCOOBJECT data type 
o CmnObjQueryObject 


═══ 10.5. CmnObjQueryObject ═══

CmnObjQueryObject 

Purpose 

This function returns an object related to the specified object in the 
specified way. 

Syntax 

(OBJERROR)CmnObjQueryObject(hcoObject,sQuery,phcoResult)

Parameters 

hcoObject (HCOOBJECT) - handle of the object to query. 

sQuery (SHORT) - specifies an OQO constant. 

phcoResult (PHCOOBJECT) - points to the variable which receives the related 
object handle. 

Returns 

This function returns one of the following values: 

OBJ_ERR_NOERROR 
OBJ_ERR_BADARGUMENT 
OBJ_ERR_BADHANDLE 
OBJ_ERR_NOTROOT 

Notes 

When used with the usNumChildren field of the COOBJECTINFO structure returned 
by CmnQueryHandleInfo, the OQO_FIRSTCHILD and OQO_NEXT constants can be used to 
traverse the entire object tree. 

Note that calling this function with OQO_ROOT is faster that calling 
CmnObjObjectFromName with "\\", because the latter calls this function. 

Related information 

o HCOOBJECT data type 
o CmnObjObjectFromName 
o CmnObjQueryObjectData 
o CmnQueryHandleInfo 


═══ 10.6. CmnObjQueryObjectData ═══

CmnObjQueryObjectData 

Purpose 

This function returns the object-specific data. 

Syntax 

(OBJERROR)CmnObjQueryObjectData(hcoObject,pvBuffer,pulSzBuf)

Parameters 

hcoObject (HCOOBJECT) - handle of the object to query. 

pvBuffer (PVOID) - points to the buffer to receive the data. If NULL, this 
function will return the number of bytes needed in pulSzBuf. 

pulSzBuf (PULONG) - points to the variable containing the size of the buffer 
pointed to by pvBuffer.  On exit, this variable contains the number of bytes 
written. 

Returns 

This function returns one of the following values: 

OBJ_ERR_NOERROR 
OBJ_ERR_BADHANDLE 

Notes 

This function should not be confused with CmnQueryHandleInfo, which returns 
information about the object's current attributes, which does include the 
object data.  Instead, this function returns only the data that was previously 
set with the CmnObjSetObjectData function. 

Related information 

o HCOOBJECT data type 
o CmnQueryHandleInfo 
o CmnObjSetObjectData 


═══ 10.7. CmnObjReset ═══

CmnObjReset 

Purpose 

This function deletes all children of the specified root object. 

Syntax 

(OBJERROR)CmnObjReset(hcoRoot)

Parameters 

hcoRoot (HCOOBJECT) - handle of the root object. 

Returns 

This function returns one of the following values: 

OBJ_ERR_NOERROR 
OBJ_ERR_BADARGUMENT 
OBJ_ERR_BADHANDLE 
OBJ_ERR_BADROOTHANDLE 
OBJ_ERR_NOTROOT 

Notes 

Use CmnObjReset to delete all children objects and their object-data and return 
the memory to the system. 

Related information 

o HCOOBJECT data type 
o CmnObjTerminate 


═══ 10.8. CmnObjSetObjectData ═══

CmnObjSetObjectData 

Purpose 

This function sets the object-specific data. 

Syntax 

(OBJERROR)CmnObjSetObjectData(hcoObject,pvBuffer,ulSzBuf)

Parameters 

hcoObject (HCOOBJECT) - handle of the object. 

pvBuffer (PVOID) - points to the buffer from which the data is copied. 

ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pvBuffer. 

Returns 

This function returns one of the following values: 

OBJ_ERR_NOERROR 
OBJ_ERR_BADARGUMENT 
OBJ_ERR_BADHANDLE 
OBJ_ERR_NOMEMORY 
OBJ_ERR_NOTROOT 
OBJ_ERR_SIZETOOLARGE 

Notes 

Use CmnObjSetObjectData to set any object-specific data which can then be later 
queried using CmnObjQueryObjectData or by examining the pvData field of the 
COOBJECTINFO structure returned from CmnQueryHandleInfo. 

Related information 

o HCOOBJECT data type 
o CmnObjQueryObjectData 
o CmnQueryHandleInfo 


═══ 10.9. CmnObjTerminate ═══

CmnObjTerminate 

Purpose 

This function destroys the object manager instance. 

Syntax 

(OBJERROR)CmnObjTerminate(phcoRoot)

Parameters 

phcoRoot (PHCOOBJECT) - handle of the root object. 

Returns 

This function returns one of the following values: 

OBJ_ERR_NOERROR 
OBJ_ERR_BADARGUMENT 
OBJ_ERR_BADHANDLE 
OBJ_ERR_BADROOTHANDLE 
OBJ_ERR_NOTROOT 

Notes 

Use CmnObjTerminate to destroy the root's children (via CmnObjReset) and to 
destroy the root object. 

Related information 

o HCOOBJECT data type 
o CmnObjInitialize 
o CmnObjReset 


═══ 11. Set routines ═══

The purpose of this group is to provide a complete set implementation. Unlike 
some programming languages, the sets are not limited to 256 elements but 
instead have a limit of approximately 520000 elements per set (for the 32-bit 
version of the library, this could conceivably be raised significantly, since 
the limit mentioned is due to the segmented architecture of 16-bit programs. 
If you are developing a 32-bit application and have a need for a higher limit, 
please let me know). Due to the fact that the sets are (currently) implemented 
as bit-maps, you should also find the performance to be very good. 

Listed below are the functions which comprise this group: 

o CmnSetClearElement 
o CmnSetClearSet 
o CmnSetCombineSets 
o CmnSetCreateSet 
o CmnSetDestroySet 
o CmnSetFindElement 
o CmnSetIntersectSets 
o CmnSetInvertElement 
o CmnSetInvertSet 
o CmnSetQueryElement 
o CmnSetQueryEqualSets 
o CmnSetSetElement 
o CmnSetSetSet 


═══ 11.1. CmnSetClearElement ═══

CmnSetClearElement 

Purpose 

This function clears an element in a set. 

Syntax 

(BOOL)CmnSetClearElement(hcsSet,ulElement);

Parameters 

hcsSet (HCSSET) - handle of the set. 

ulElement (ULONG) - specifies the 0-based element to clear. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSetClearElement to clear an element from a set.  To clear all of the 
elements in a set, use CmnSetClearSet. 

Related information 

o HCSSET data type 
o CmnSetClearSet 


═══ 11.2. CmnSetClearSet ═══

CmnSetClearSet 

Purpose 

This function clears all of the elements in a set. 

Syntax 

(BOOL)CmnSetClearSet(hcsSet);

Parameters 

hcsSet (HCSSET) - handle of the set to clear. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSetClearSet to clear all of the elements in a set. To clear a single 
element, use CmnSetClearElement. 

This call is fast in terms of execution time. 

Related information 

o HCSSET data type 
o CmnSetClearElement 


═══ 11.3. CmnSetCombineSets ═══

CmnSetCombineSets 

Purpose 

This function creates a new set containing all of the elements set from two 
sets. 

Syntax 

(HCSSET)CmnSetCombineSets(hcsSet1,hcsSet2);

Parameters 

hcsSet1 (HCSSET) - handle of a set to combine. 

hcsSet2 (HCSSET) - handle of a set to combine. 

Returns 

This function returns a handle to the resulting set if successful, or NULL 
otherwise. 

Notes 

Use CmnSetCombineSets to perform a union of two sets.  Note that the two sets 
do not have to be of equal size. 

To perform an intersection of two sets, use CmnSetIntersectSets. 

Related information 

o HCSSET data type 
o CmnSetIntersectSets 


═══ 11.4. CmnSetCreateSet ═══

CmnSetCreateSet 

Purpose 

This function creates a new set handle for use in subsequent calls to the 
CmnSet functions. 

Syntax 

(BOOL)CmnSetCreateSet(ulMaxElems,phcsSet);

Parameters 

ulMaxElems (ULONG) - specifies the maximum number of elements the set is to 
hold. 

phcsSet (PHCSSET) - points to the variable to receive the created set handle. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSetCreateSet to create a new set for use in subsequent calls to the 
CmnSet functions.  Note that there is currently an upper limit of 522240 for 
ulMaxElems. 

Related information 

o HCSSET data type 
o CmnSetDestroySet 


═══ 11.5. CmnSetDestroySet ═══

CmnSetDestroySet 

Purpose 

This function destroys a set handle. 

Syntax 

(BOOL)CmnSetDestroySet(phcsSet);

Parameters 

phcsSet (PHCSSET) - points to the variable containing the handle of the set to 
destroy.  On return, the variable contains NULL. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSetDestroySet to destroy a handle to a set and return any memory to the 
system. 

Related information 

o HCSSET data type 
o CmnSetCreateSet 


═══ 11.6. CmnSetFindElement ═══

CmnSetFindElement 

Purpose 

This function finds the nth element in a set that is either set or clear. 

Syntax 

(LONG)CmnSetFindElement(hcsSet,ulNumber,usType)

Parameters 

hcsSet (HCSSET) - handle of the set. 

ulNumber (ULONG) - specifies the nth element to find. 

usType (USHORT) - specifies a SFE_ constant. 

Returns 

This function returns the index of the element found, SFE_NOTFOUND if the nth 
element was not found, or SFE_ERROR if an error occurred. 

Notes 

Use CmnSetFindElement to find the nth element set or clear in a set (i.e. the 
3rd clear element). 

Related information 

o HCSSET data type 
o CmnSetClearElement 
o CmnSetSetElement 


═══ 11.7. CmnSetIntersectSets ═══

CmnSetIntersectSets 

Purpose 

This function creates a new set containing elements that were set in both of 
the specified sets. 

Syntax 

(HCSSET)CmnSetIntersectSets(hcsSet1,hcsSet2);

Parameters 

hcsSet1 (HCSSET) - handle of a set to intersect. 

hcsSet2 (HCSSET) - handle of a set to intersect. 

Returns 

This function returns a handle to the resulting set if successful, or NULL 
otherwise. 

Notes 

Use CmnSetIntersectSets to perform an intersection of two sets. Note that the 
two sets do not have to be of equal size. 

Related information 

o HCSSET data type 
o CmnSetCombineSets 


═══ 11.8. CmnSetInvertElement ═══

CmnSetInvertElement 

Purpose 

This function inverts the state of an element in a set. 

Syntax 

(BOOL)CmnSetInvertElement(hcsSet,ulElement);

Parameters 

hcsSet (HCSSET) - handle of the set. 

ulElement (ULONG) - specifies the 0-based element to invert. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSetInvertElement to invert an element in a set.  That is, if it was set, 
it is cleared (and vice versa).  To invert an entire set, use CmnSetInvertSet. 

Related information 

o HCSSET data type 
o CmnSetInvertSet 


═══ 11.9. CmnSetInvertSet ═══

CmnSetInvertSet 

Purpose 

This function inverts the state of all of the elements in a set. 

Syntax 

(BOOL)CmnSetInvertSet(hcsSet);

Parameters 

hcsSet (HCSSET) - handle of the set to invert. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSetInvertSet to invert all of the elements of a set.  To invert a single 
element, use CmnSetInvertElement. 

This call is fast in terms of execution time. 

Related information 

o HCSSET data type 
o CmnSetInvertElement 


═══ 11.10. CmnSetQueryElement ═══

CmnSetQueryElement 

Purpose 

This function queries the state of an element in a set. 

Syntax 

(SHORT)CmnSetQueryElement(hcsSet,ulElement);

Parameters 

hcsSet (HCSSET) - handle of the set to query. 

ulElement (ULONG) - specifies the 0-based element to query. 

Returns 

This function returns SQE_SET if the element is set, SQE_CLEAR if the element 
is cleared, or SQE_ERROR if an error occurred. 

Notes 

Use CmnSetQueryElement to query the state of an element. 

Related information 

o HCSSET data type 


═══ 11.11. CmnSetQueryEqualSets ═══

CmnSetQueryEqualSets 

Purpose 

This function determines whether or not two sets are equal. 

Syntax 

(SHORT)CmnSetQueryEqualSets(hcsSet1,hcsSet2);

Parameters 

hcsSet1 (HCSSET) - handle of a set to compare. 

hcsSet2 (HCSSET) - handle of a set to compare. 

Returns 

This function returns SQES_EQUAL if the sets have the same number of elements 
and the same elements are set in both sets, SQES_NOTEQUAL if the sets do not 
have the same number of elements or the same elements are not set in both sets, 
or SQES_ERROR if an error occurred. 

Notes 

Use CmnSetQueryEqualSets to determine whether or not two sets are equal. 

This call is fast in terms of execution time. 

Related information 

o HCSSET data type 


═══ 11.12. CmnSetSetElement ═══

CmnSetSetElement 

Purpose 

This function sets an element in a set. 

Syntax 

(BOOL)CmnSetSetElement(hcsSet,ulElement);

Parameters 

hcsSet (HCSSET) - handle of the set. 

ulElement (ULONG) - specifies the 0-based element to set. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSetSetElement to set an element in a set.  To set all of the elements in 
a set, use CmnSetSetSet. 

Related information 

o HCSSET data type 
o CmnSetSetSet 


═══ 11.13. CmnSetSetSet ═══

CmnSetSetSet 

Purpose 

This function sets all of the elements in a set. 

Syntax 

(BOOL)CmnSetSetSet(hcsSet);

Parameters 

hcsSet (HCSSET) - handle of the set to set. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSetSetSet to set all of the elements in a set. To set a single element, 
use CmnSetSetElement. 

This call is fast in terms of execution time. 

Related information 

o HCSSET data type 
o CmnSetSetElement 


═══ 12. Signal routines ═══

The purpose of this group is to provide an easy method of communication between 
different threads in an application.  Signals can either be via 32-bit values 
or individual bits in a 32-bit word, and can be waited on like you can with 
semaphores.  Unfortunately, since this functions are not system-wide objects, 
they cannot be used for interprocess communication. 

Listed below are the functions which comprise this group: 

o CmnSigClearAllSignalBits 
o CmnSigClearSignalBit 
o CmnSigCreateSignal 
o CmnSigCreateSignalList 
o CmnSigDestroySignal 
o CmnSigDestroySignalList 
o CmnSigQuerySignal 
o CmnSigQuerySignalId 
o CmnSigQuerySignalValue 
o CmnSigSetAllSignalBits 
o CmnSigSetAllSignalValues 
o CmnSigSetSignalBit 
o CmnSigSetSignalValue 
o CmnSigWaitAllSignalBits 
o CmnSigWaitAllSignalValues 
o CmnSigWaitSignalBit 
o CmnSigWaitSignalValue 


═══ 12.1. CmnSigClearAllSignalBits ═══

CmnSigClearAllSignalBits 

Purpose 

This function clears all of the specified bits in all of the signal handles in 
a signal list. 

Syntax 

(BOOL)CmnSigClearAllSignalBits(hcsList,ulSignal);

Parameters

hcsList (HCSSIGNALLIST) - handle to the signal list. 

ulSignal (ULONG) - specifies one or more bits to clear. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSigClearAllSignalBits to clear all of the specified bits in all of the 
signal handles in a signal list.  To clear specified bits from a single signal 
handle, use CmnSigClearSignalBit. 

Related information 

o HCSSIGNALLIST data type 
o CmnSigClearSignalBit 
o CmnSigSetAllSignalBits 


═══ 12.2. CmnSigClearSignalBit ═══

CmnSigClearSignalBit 

Purpose 

This function clears one or more bits in a signal. 

Syntax 

(BOOL)CmnSigClearSignalBit(hcSignal,ulSignal);

Parameters 

hcSignal (HCSSIGNAL) - handle to the signal. 

ulSignal (ULONG) - specifies one or more bits to clear. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSigClearSignalBit to clear one or more bits from a signal. 

Related information 

o HCSSIGNAL data type 
o CmnSigSetSignalBit 


═══ 12.3. CmnSigCreateSignal ═══

CmnSigCreateSignal 

Purpose 

This function creates a signal handle within a signal list. 

Syntax 

(BOOL)CmnSigCreateSignal(hcsList,ulId,phcSignal);

Parameters 

hcsList (HCSSIGNALLIST) - handle to the signal list to which the signal handle 
will belong. 

ulId (ULONG) - specified the identifer of the signal handle. This must be 
unique. 

phcSignal (PHCSSIGNAL) - points to the variable to receive the created signal 
handle. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSigCreateSignal to create a signal handle for use in subsequent calls to 
the CmnSig routines.  ulId must be a unique identifier within the signal list. 

Note that because this function requires the handle to a signal list, 
CmnSigCreateSignalList must be called prior to using this function. 

Related information 

o HCSSIGNALLIST data type 
o HCSSIGNAL data type 
o CmnSigCreateSignalList 
o CmnSigDestroySignal 


═══ 12.4. CmnSigCreateSignalList ═══

CmnSigCreateSignalList 

Purpose 

This function creates a signal list handle from which signal handles can be 
created. 

Syntax 

(BOOL)CmnSigCreateSignalList(phcsList);

Parameters 

phcsList (PHCSSIGNALLIST) - points to the variable that receives the created 
signal list handle. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSigCreateSignalList to create a signal list handle. After this is 
created, CmnSigCreateSignal can be called to create signal handles to be used 
in other CmnSig functions. 

Related information 

o HCSSIGNALLIST data type 
o CmnSigCreateSignal 
o CmnSigDestroySignalList 


═══ 12.5. CmnSigDestroySignal ═══

CmnSigDestroySignal 

Purpose 

This function destroys a signal handle. 

Syntax 

(BOOL)CmnSigDestroySignal(phcSignal);

Parameters 

phcSignal (PHCSSIGNAL) - points to the variable which specifies the handle of 
the signal to destroy.  On return, this variable contains NULL. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSigDestroySignal to destroy a signal handle.  This call is not required 
prior to calling CmnSigDestroySignalList because it will destroy all signal 
handles belong to the signal list. 

Related information 

o HCSSIGNAL data type 
o CmnSigCreateSignal 


═══ 12.6. CmnSigDestroySignalList ═══

CmnSigDestroySignalList 

Purpose 

This function destroys a signal list. 

Syntax 

(BOOL)CmnSigDestroySignalList(phcsList);

Parameters 

phcsList (PHCSSIGNALLIST) - points to the variable which specifies the handle 
of the signal list to destroy.  On return, this variable contains NULL. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSigDestroySignalList to destroy a signal list and all associated signal 
handles. 

Related information 

o HCSSIGNALLIST data type 
o CmnSigCreateSignalList 


═══ 12.7. CmnSigQuerySignal ═══

CmnSigQuerySignal 

Purpose 

This function queries a signal list for a signal handle with a specific 
identifier. 

Syntax 

(BOOL)CmnSigQuerySignal(hcsList,ulId,phcSignal);

Parameters 

hcsList (HCSSIGNALLIST) - handle to the signal list to query. 

ulId (ULONG) - specifies the identifier of the signal handle desired. 

phcSignal (PHCSSIGNAL) - points to the variable to receive the result.  On 
return, the variable contains the signal handle with the specified identifier. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSigQuerySignal to query a signal list for the signal handle that was 
created with the specified identifier. 

Related information 

o HCSSIGNAL data type 
o HCSSIGNALLIST data type 
o CmnSigCreateSignal 
o CmnSigQuerySignalId 


═══ 12.8. CmnSigQuerySignalId ═══

CmnSigQuerySignalId 

Purpose 

This function returns the identifier of a signal handle. 

Syntax 

(BOOL)CmnSigQuerySignalId(hcSignal,pulId);

Parameters 

hcSignal (HCSSIGNAL) - handle to the signal. 

pulId (PULONG) - points to the variable that receives the identifier of the 
signal handle. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSigQuerySignalId to query the identifier of a signal handle.  This 
identifier is specified when the signal handle is created. 

Related information 

o HCSSIGNAL data type 
o CmnSigCreateSignal 


═══ 12.9. CmnSigQuerySignalValue ═══

CmnSigQuerySignalValue 

Purpose 

This function queries the current value of a signal handle. 

Syntax 

(BOOL)CmnSigQuerySignalValue(hcSignal,pulSignal);

Parameters 

hcSignal (HCSSIGNAL) - handle to the signal. 

pulSignal (PULONG) - points to the variable that receives the value of the 
signal handle. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSigQuerySignalValue to query the current value of a signal handle. 

Related information 

o HCSSIGNAL data type 
o CmnSigSetSignalValue 


═══ 12.10. CmnSigSetAllSignalBits ═══

CmnSigSetAllSignalBits 

Purpose 

This function sets specific bits in all signals in a signal list. 

Syntax 

(BOOL)CmnSigSetAllSignalBits(hcsList,ulSignal);

Parameters

hcsList (HCSSIGNALLIST) - handle to the signal list. 

ulSignal (ULONG) - specifies one or more bits to set. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSigSetAllSignalBits to set a specific set of bits in all signals in a 
signal list.  This could be used to reset the acknowledgement signal from 
multiple threads by the initiator of the inter-thread conversation. 

Related information 

o HCSSIGNALLIST data type 
o CmnSigClearAllSignalBits 
o CmnSigSetAllSignalValues 


═══ 12.11. CmnSigSetAllSignalValues ═══

CmnSigSetAllSignalValues 

Purpose 

This function sets all of the signal values in a signal list to a specific 
value. 

Syntax 

(BOOL)CmnSigSetAllSignalValues(hcsList,ulSignal);

Parameters

hcsList (HCSSIGNALLIST) - handle to the signal list. 

ulSignal (ULONG) - specifies the new signal value. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSigSetAllSignalValues to set all of the signal values in a signal list 
to a specific value.  This could be used to reset the acknowledgement signal 
from multiple threads by the initiator of the inter-thread conversation. 

Related information 

o HCSSIGNALLIST data type 
o CmnSigSetAllSignalBits 


═══ 12.12. CmnSigSetSignalValue ═══

CmnSigSetSignalValue 

Purpose 

This function sets the current value of a signal handle. 

Syntax 

(BOOL)CmnSigSetSignalValue(hcSignal,ulSignal);

Parameters 

hcSignal (HCSSIGNAL) - handle to the signal. 

ulSignal (ULONG) - specifies the new value of the signal. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSigSetSignalValue to set the current value of a signal value.  To set or 
clear individual bits of the signal value, use CmnSigSetSignalBit and 
CmnSigClearSignalBit. 

Related information 

o HCSSIGNAL data type 
o CmnSigClearSignalBit 
o CmnSigQuerySignalValue 
o CmnSigSetSignalBit 


═══ 12.13. CmnSigSetSignalBit ═══

CmnSigSetSignalBit 

Purpose 

This function sets one or more bits in a signal. 

Syntax 

(BOOL)CmnSigSetSignalBit(hcSignal,ulSignal);

Parameters 

hcSignal (HCSSIGNAL) - handle to the signal. 

ulSignal (ULONG) - specifies one or more bits to set. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnSigSetSignalBit to set one or more bits in a signal. 

Related information 

o HCSSIGNAL data type 
o CmnSigClearSignalBit 


═══ 12.14. CmnSigWaitAllSignalBits ═══

CmnSigWaitAllSignalBits 

Purpose 

This function waits until all of the specified bits are set in all of the 
signal handles belonging to a signal list. 

Syntax 

(USHORT)CmnSigWaitAllSignalBits(hcsList,ulSignal,lTimeout);

Parameters 

hcsList (HCSSIGNALLIST) - handle to the signal list. 

ulSignal (ULONG) - specifies the bits to wait for. 

lTimeout (LONG) - specifies the timeout in milliseconds, or an SWS_TIMEOUT_ 
constant. 

Returns 

This function returns SWS_RC_SIGNALSET if all of the signal handles had the 
bits set, SWS_RC_TIMEOUT if a timeout occurred, or SWS_RC_ERROR if an error 
occurred. 

Notes 

Use CmnSigWaitAllSignalBits to wait for all of the specified bits in all of the 
signal handles in a signal list to be set.  This could be used as part of a 
handshaking mechanism, where one thread calls CmnSigSetAllSignalBits to 
indicate to the other threads that some function is to be performed and then 
follows with a call to this function to wait for each signal to indicate (via 
CmnSigSetSignalBit) that it has completed the request. 

Related information 

o SWS_TIMEOUT_ constants 
o HCSSIGNALLIST data type 
o CmnSigClearAllSignalBits 
o CmnSigSetAllSignalValues 
o CmnSigWaitAllSignalValues 


═══ 12.15. CmnSigWaitAllSignalValues ═══

CmnSigWaitAllSignalValues 

Purpose 

This function waits until all of the signal values in a signal list are equal 
to a specific value. 

Syntax 

(USHORT)CmnSigWaitAllSignalValues(hcsList,ulSignal,lTimeout);

Parameters 

hcsList (HCSSIGNALLIST) - handle to the signal list. 

ulSignal (ULONG) - specifies the value to wait for. 

lTimeout (LONG) - specifies the timeout in milliseconds, or an SWS_TIMEOUT_ 
constant. 

Returns 

This function returns SWS_RC_SIGNALSET if all of the signal handles had the 
bits set, SWS_RC_TIMEOUT if a timeout occurred, or SWS_RC_ERROR if an error 
occurred. 

Notes 

Use CmnSigWaitAllSignalValues to wait for all signal values in a signal list to 
equal a specific value.  This could be used to wait for an acknowledgement from 
multiple threads after they have finished processing a task. 

Related information 

o SWS_TIMEOUT_ constants 
o HCSSIGNALLIST data type 
o CmnSigSetAllSignalValues 
o CmnSigWaitAllSignalBits 


═══ 12.16. CmnSigWaitSignalBit ═══

CmnSigWaitSignalBit 

Purpose 

This function waits for a specific set of bits to be set in a signal handle. 

Syntax 

(USHORT)CmnSigWaitSignalBit(hcSignal,ulSignal,lTimeout);

Parameters 

hcSignal (HCSSIGNAL) - handle to the signal. 

ulSignal (ULONG) - specifies one or more bits to wait for. 

lTimeout (LONG) - specifies the timeout in milliseconds, or an SWS_TIMEOUT_ 
constant. 

Returns 

This function returns SWS_RC_SIGNALSET if all of the signal handles had the 
bits set, SWS_RC_TIMEOUT if a timeout occurred, or SWS_RC_ERROR if an error 
occurred. 

Notes 

Use CmnSigWaitSignalBit to wait for a specific set of bits in a signal handle 
to be set.  This could be used by a thread to wait until a bit is set before 
performing some action. 

Related information 

o SWS_TIMEOUT_ constants 
o HCSSIGNAL data type 
o CmnSigClearSignalBit 
o CmnSigSetSignalBit 


═══ 12.17. CmnSigWaitSignalValue ═══

CmnSigWaitSignalValue 

Purpose 

This function waits until the value of a signal handle equals a specific value. 

Syntax 

(USHORT)CmnSigWaitSignalValue(hcSignal,ulSignal,lTimeout);

Parameters 

hcSignal (HCSSIGNAL) - handle to the signal. 

ulSignal (ULONG) - specifies the value to wait for. 

lTimeout (LONG) - specifies the timeout in milliseconds, or an SWS_TIMEOUT_ 
constant. 

Returns 

This function returns SWS_RC_SIGNALSET if all of the signal handles had the 
bits set, SWS_RC_TIMEOUT if a timeout occurred, or SWS_RC_ERROR if an error 
occurred. 

Notes 

Use CmnSigWaitSignalValue to wait for the value of a signal handle equals a 
specific value.  This could be used in a handshaking protocol between multiple 
threads. 

Related information 

o SWS_TIMEOUT_ constants 
o HCSSIGNAL data type 
o CmnSigSetSignalValue 


═══ 13. Sprite routines ═══

The purpose of this group is to provide the capability to draw bitmaps with 
transparancy; the difference between a sprite resource and the system-defined 
pointer resource is that pointer are always the same size (determined by 
calling WinQuerySysValue with the SV_CXICON and SV_CYICON constants), while 
sprites can be any size, up to a maximum of MAX_SPRITE_CX by MAX_SPRITE_CY 
pels. 

Sprites are often used in animated sequences; however, while this group 
provides a basis for sprite manipulation, the animation is still up to the 
programmer to accomplish. 

Before a sprite can be drawn on the screen, it must belong to a playground.  A 
playground maintains a membership list and can have either a background bitmap 
or color associated with it.  Although the concept of a background seems 
superfluous, it is necessary for the transparency capabilities. 

Listed below are the functions which comprise this group: 

o CmnSprAddSprite 
o CmnSprCreatePlayground 
o CmnSprCreateSprite 
o CmnSprDestroyPlayground 
o CmnSprDestroySprite 
o CmnSprDrawPlayground 
o CmnSprDrawSprite 
o CmnSprQueryLayering 
o CmnSprQueryPlaygroundBack 
o CmnSprQueryPlaygroundColor 
o CmnSprQueryPlaygroundSize 
o CmnSprQuerySpritePosition 
o CmnSprQuerySpriteRect 
o CmnSprQuerySpriteSize 
o CmnSprQuerySpriteVisibility 
o CmnSprQueryUpdateFlag 
o CmnSprRemoveSprite 
o CmnSprSetLayering 
o CmnSprSetPlaygroundBack 
o CmnSprSetPlaygroundColor 
o CmnSprSetPlaygroundSize 
o CmnSprSetSpritePosition 
o CmnSprSetSpriteVisibility 
o CmnSprSetUpdateFlag 


═══ 13.1. CmnSprAddSprite ═══

CmnSprAddSprite 

Purpose 

This function adds a sprite to a playground so that it may be drawn, moved, 
etc. 

Syntax 

(SPRERROR)CmnSprAddSprite(hpgPlay,hsSprite);

Parameters 

hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 

hsSprite (HCSSPRITE) - handle of the sprite instance. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 
SPR_ERR_HASPLAYGROUND 
SPR_ERR_PLAYGROUNDFULL 

Notes 

Once a sprite is added to a playground, it may not be destroyed until it is 
removed from the playground.  A sprite may belong to one playground only at any 
given time, and a playground can hold up to MAX_SPRITES number of sprites at 
any given time. 

Related information 

o HCSPLAYGROUND data type 
o HCSSPRITE data type 
o CmnSprCreateSprite 
o CmnSprDestroySprite 
o CmnSprRemoveSprite 


═══ 13.2. CmnSprCreatePlayground ═══

CmnSprCreatePlayground 

Purpose 

This function creates a playground instance to which sprites may be added. 

Syntax 

(SPRERROR)CmnSprCreatePlayground(habAnchor,phpgPlay);

Parameters 

habAnchor (HAB) - handle of the anchor block of the calling thread. 

phpgPlay (PHCSPLAYGROUND) - points to the variable to receive the handle of the 
playground. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_NOMEMORY 
SPR_ERR_RESOURCE 

Notes 

Although specifying an anchor block might imply otherwise, playground handles 
are not specific to a thread, but instead belong to the entire process. 

A playground is created with the following defaults: 

Update flag         TRUE 
Background          Color, which is CLR_BLACK 
Size                Height and width of 0 

Related information 

o HCSPLAYGROUND data type 
o CmnSprDestroyPlayground 


═══ 13.3. CmnSprCreateSprite ═══

CmnSprCreateSprite 

Purpose 

This function creates a sprite instance which may be added to a playground. 

Syntax 

(SPRERROR)CmnSprCreateSprite(habAnchor,hbmBitmap,phsSprite);

Parameters 

habAnchor (HAB) - handle of the anchor block of the calling thread. 

hbmBitmap (HBITMAP) - handle of the bitmap from which to create the sprite. 

phsSprite (PHCSSPRITE) - points to the variable to receive the handle of the 
sprite. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 
SPR_ERR_NOMEMORY 
SPR_ERR_RESOURCE 

Notes 

All pels in the bitmap that, once mapped to the physical palette, are black 
specify the transparent portions of the sprite.  The bitmap that is passed in 
cannot have a wider greater than MAX_SPRITE_CX pels or a height greater than 
MAX_SPRITE_CY or the function will fail with error SPR_ERR_BADHANDLE.  Once 
this function returns SPR_ERR_NOERROR, the bitmap handle (hbmBitmap) is 
considered to be owned by the sprite subsystem and should not be deleted by the 
application, unless by calling CmnSprDestroySprite. 

Like the playground, a sprite belongs to the entire process that created it, 
instead of just the thread as the anchor block parameter would imply. 

A sprite is created with the following defaults: 

Visibility          Not visible 
Position            (0,0) 

Related information 

o HCSSPRITE data type 
o CmnSprDestroySprite 


═══ 13.4. CmnSprDestroyPlayground ═══

CmnSprDestroyPlayground 

Purpose 

This function destroys the playground instance, all sprites that still belong 
to it, and the background bitmap if one exists. 

Syntax 

(SPRERROR)CmnSprDestroyPlayground(hpgPlay);

Parameters 

hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 

Related information 

o HCSPLAYGROUND data type 
o CmnSprCreatePlayground 


═══ 13.5. CmnSprDestroySprite ═══

CmnSprDestroySprite 

Purpose 

This function destroys the sprite instance, including any associated bitmaps. 

Syntax 

(SPRERROR)CmnSprDestroySprite(hsSprite);

Parameters 

hsSprite (HCSSPRITE) - handle of the sprite instance. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 
SPR_ERR_HASPLAYGROUND 

Notes 

If the sprite still belongs to a playground, this function fails with the error 
SPR_ERR_HASPLAYGROUND. 

Related information 

o HCSSPRITE data type 
o CmnSprCreateSprite 


═══ 13.6. CmnSprDrawPlayground ═══

CmnSprDrawPlayground 

Purpose 

This function redraws the entire playground, including any sprites belonging to 
it. 

Syntax 

(SPRERROR)CmnSprDrawPlayground(hpsDraw,hpgPlay);

Parameters 

hpsDraw (HPS) - handle of the presentation space to draw within. 

hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 

Related information 

o HCSPLAYGROUND data type 
o CmnSprDrawSprite 


═══ 13.7. CmnSprDrawSprite ═══

CmnSprDrawSprite 

Purpose 

This function draws the sprite at its current position. 

Syntax 

(SPRERROR)CmnSprDrawSprite(hpsDraw,hsSprite);

Parameters 

hpsDraw (HPS) - handle of the presentation space to draw within. 

hsSprite (HCSSPRITE) - handle of the sprite instance. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 
SPR_ERR_HASNOPLAYGROUND 

Notes 

If the sprite's visibility flag is FALSE (see CmnSprSetSpriteVisibility), this 
function returns SPR_ERR_NOERROR, but no drawing takes place. 

Changing the position or visibility state of the sprite automatically redraws 
the sprite without forcing you to call this function. 

Related information 

o HCSSPRITE data type 
o CmnSprDrawPlayground 


═══ 13.8. CmnSprQueryLayering ═══

CmnSprQueryLayering 

Purpose 

This function returns the layer of the sprite within the z-order. 

Syntax 

(SPRERROR)CmnSprQueryLayering(hsSprite,plPos);

Parameters 

hsSprite (HCSSPRITE) - handle of the sprite instance. 

plPos (PLONG) - points to the variable to receive the index of the sprite. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 
SPR_ERR_HASNOPLAYGROUND 
SPR_ERR_NOTFOUND 

Related information 

o CmnSprSetLayering 


═══ 13.9. CmnSprQueryPlaygroundBack ═══

CmnSprQueryPlaygroundBack 

Purpose 

This function returns the handle of the playground background bitmap. 

Syntax 

(SPRERROR)CmnSprQueryPlaygroundBack(hpgPlay,phbmBack);

Parameters 

hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 

phbmBack (HBITMAP *) - points to the variable to receive the bitmap handle. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 

Notes 

The playground still owns the bitmap handle returned.  To specify that the 
playground should relinquish ownership, use the CmnSprSetPlaygroundBack 
function. 

Related information 

o HCSPLAYGROUND data type 
o CmnSprQueryPlaygroundColor 
o CmnSprQueryPlaygroundSize 
o CmnSprSetPlaygroundBack 
o CmnSprSetPlaygroundColor 
o CmnSprSetPlaygroundSize 


═══ 13.10. CmnSprQueryPlaygroundColor ═══

CmnSprQueryPlaygroundColor 

Purpose 

This function returns the current background color. 

Syntax 

(SPRERROR)CmnSprQueryPlaygroundColor(hpgPlay,plBackColor);

Parameters 

hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 

plBackColor (PLONG) - points to the variable to receive the current background 
color. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 
SPR_ERR_HASBACKGROUND 

Notes 

If the playground has a background bitmap, this function fails with the error 
SPR_ERR_HASBACKGROUND since the two are mutually exclusive properties. 

Related information 

o HCSPLAYGROUND data type 
o CmnSprQueryPlaygroundBack 
o CmnSprQueryPlaygroundSize 
o CmnSprSetPlaygroundBack 
o CmnSprSetPlaygroundColor 
o CmnSprSetPlaygroundSize 


═══ 13.11. CmnSprQueryPlaygroundSize ═══

CmnSprQueryPlaygroundSize 

Purpose 

This function returns the current background size. 

Syntax 

(SPRERROR)CmnSprQueryPlaygroundSize(hpgPlay,pszlSize);

Parameters 

hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 

pszlSize (PSIZEL) - points to the variable to receive the current background 
size. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 

Notes 

If the playground has a background bitmap, this function fails with the error 
SPR_ERR_HASBACKGROUND since the two are mutually exclusive properties. 

Related information 

o HCSPLAYGROUND data type 
o CmnSprQueryPlaygroundBack 
o CmnSprQueryPlaygroundColor 
o CmnSprSetPlaygroundBack 
o CmnSprSetPlaygroundColor 
o CmnSprSetPlaygroundSize 


═══ 13.12. CmnSprQuerySpritePosition ═══

CmnSprQuerySpritePosition 

Purpose 

This function returns the position of the sprite. 

Syntax 

(SPRERROR)CmnSprQuerySpritePosition(hsSprite,pptlPos);

Parameters 

hsSprite (HCSSPRITE) - handle of the sprite instance. 

pptlPos (PPOINTL) - points to the variable to receive the position of the 
sprite. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 
SPR_ERR_HASNOPLAYGROUND 

Notes 

The sprite must belong to a playground to have a position associated with it. 

Related information 

o HCSSPRITE data type 
o CmnSprAddSprite 
o CmnSprQuerySpriteRect 
o CmnSprQuerySpriteSize 
o CmnSprQuerySpriteVisibility 
o CmnSprRemoveSprite 
o CmnSprSetSpritePosition 
o CmnSprSetSpriteVisibility 


═══ 13.13. CmnSprQuerySpriteRect ═══

CmnSprQuerySpriteRect 

Purpose 

This function returns the bounding rectangle of the sprite. 

Syntax 

(SPRERROR)CmnSprQuerySpriteRect(hsSprite,prclRect);

Parameters 

hsSprite (HCSSPRITE) - handle of the sprite instance. 

prclRect (PRECTL) - points to the variable to receive the bounding rectangle of 
the sprite. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 
SPR_ERR_HASNOPLAYGROUND 

Notes 

The sprite must belong to a playground to have a position and size associated 
with it.  The bounding rectangle is calculated as follows: 

prclRect->xLeft=(current x position)
prclRect->yBottom=(current y position)
prclRect->xRight=prclRect->xLeft + (width of the original bitmap passed to
                                    CmnSprCreateSprite) - 1
prclRect->yTop=prclRect->yBottom + (height of the original bitmap passed to
                                    CmnSprCreateSprite) - 1

Related information 

o HCSSPRITE data type 
o CmnSprAddSprite 
o CmnSprQuerySpritePosition 
o CmnSprQuerySpriteSize 
o CmnSprQuerySpriteVisibility 
o CmnSprRemoveSprite 
o CmnSprSetSpritePosition 
o CmnSprSetSpriteVisibility 


═══ 13.14. CmnSprQuerySpriteSize ═══

CmnSprQuerySpriteSize 

Purpose 

This function returns the size of the sprite. 

Syntax 

(SPRERROR)CmnSprQuerySpriteSize(hsSprite,pszlSize);

Parameters 

hsSprite (HCSSPRITE) - handle of the sprite instance. 

pszlSize (PSIZEL) - points to the variable to receive the size of the sprite. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 

Notes 

Since the size of a sprite is static, this is the only function returning the 
value of a sprite characteristic which does not require the sprite to belong to 
a playground. 

Related information 

o HCSSPRITE data type 
o CmnSprAddSprite 
o CmnSprQuerySpritePosition 
o CmnSprQuerySpriteRect 
o CmnSprQuerySpriteVisibility 
o CmnSprRemoveSprite 
o CmnSprSetSpritePosition 
o CmnSprSetSpriteVisibility 


═══ 13.15. CmnSprQuerySpriteVisibility ═══

CmnSprQuerySpriteVisibility 

Purpose 

This function returns the visibility of the sprite. 

Syntax 

(SPRERROR)CmnSprQuerySpriteVisibility(hsSprite,pbVisible);

Parameters 

hsSprite (HCSSPRITE) - handle of the sprite instance. 

pbVisible (PBOOL) - points to the variable to receive the visibility state of 
the sprite. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 
SPR_ERR_HASNOPLAYGROUND 

Notes 

The sprite must belong to a playground to have a visibility state associated 
with it. 

Related information 

o HCSSPRITE data type 
o CmnSprAddSprite 
o CmnSprQuerySpritePosition 
o CmnSprQuerySpriteRect 
o CmnSprQuerySpriteSize 
o CmnSprRemoveSprite 
o CmnSprSetSpritePosition 
o CmnSprSetSpriteVisibility 


═══ 13.16. CmnSprQueryUpdateFlag ═══

CmnSprQueryUpdateFlag 

Purpose 

This function returns the value of the update flag of a playground. 

Syntax 

(SPRERROR)CmnSprQueryUpdateFlag(hpgPlay,pbUpdate);

Parameters 

hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 

pbUpdate (PBOOL) - points to the variable to receive the update flag of the 
playground. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 

Related information 

o HCSPLAYGROUND data type 
o CmnSprSetUpdateFlag 


═══ 13.17. CmnSprRemoveSprite ═══

CmnSprRemoveSprite 

Purpose 

This function removes a sprite from a playground. 

Syntax 

(SPRERROR)CmnSprRemoveSprite(hpgPlay,hsSprite);

Parameters 

hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 

hsSprite (HCSSPRITE) - handle of the sprite instance. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 
SPR_ERR_HASNOPLAYGROUND 

Notes 

This function must be called before the sprite can be destroyed. 

Related information 

o HCSPLAYGROUND data type 
o HCSSPRITE data type 
o CmnSprAddSprite 
o CmnSprCreateSprite 
o CmnSprDestroySprite 


═══ 13.18. CmnSprSetLayering ═══

CmnSprSetLayering 

Purpose 

This function sets the layer of the sprite in the z-order. 

Syntax 

(SPRERROR)CmnSprSetLayering(hpsDraw,hsSprite,lPos);

Parameters 

hpsDraw (HPS) - handle of the presentation space to draw within. 

hsSprite (HCSSPRITE) - handle of the sprite instance. 

lPos (LONG) - specifies the new layer of the sprite. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 
SPR_ERR_HASNOPLAYGROUND 

Related information 

o CmnSprQueryLayering 


═══ 13.19. CmnSprSetPlaygroundBack ═══

CmnSprSetPlaygroundBack 

Purpose 

This function sets the bitmap to be used for the background. 

Syntax 

(SPRERROR)CmnSprSetPlaygroundBack(hpgPlay,hbmNew,phbmOld);

Parameters 

hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 

hbmNew (HBITMAP) - handle of the new background bitmap. 

phbmOld (HBITMAP *) - points to the variable to receive the handle of current 
background bitmap.  This may be NULL. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 

Notes 

The playground also relinquishes ownership of the current background bitmap, 
meaning it becomes the application's responsibility to insure it is deleted 
before the application exits. 

Related information 

o HCSPLAYGROUND data type 
o CmnSprQueryPlaygroundBack 
o CmnSprQueryPlaygroundColor 
o CmnSprQueryPlaygroundSize 
o CmnSprSetPlaygroundColor 
o CmnSprSetPlaygroundSize 


═══ 13.20. CmnSprSetPlaygroundColor ═══

CmnSprSetPlaygroundColor 

Purpose 

This function sets the current background color. 

Syntax 

(SPRERROR)CmnSprSetPlaygroundColor(hpgPlay,lBackColor);

Parameters 

hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 

lBackColor (LONG) - specifies the new background color. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 
SPR_ERR_HASBACKGROUND 

Notes 

If the playground has a background bitmap, this function fails with error 
SPR_ERR_HASBACKGROUND since the two properties are mutual exclusive. 

Related information 

o HCSPLAYGROUND data type 
o CmnSprQueryPlaygroundBack 
o CmnSprQueryPlaygroundColor 
o CmnSprQueryPlaygroundSize 
o CmnSprSetPlaygroundBack 
o CmnSprSetPlaygroundSize 


═══ 13.21. CmnSprSetPlaygroundSize ═══

CmnSprSetPlaygroundSize 

Purpose 

This function sets the size of the playground. 

Syntax 

(SPRERROR)CmnSprSetPlaygroundSize(hpgPlay,pszlSize);

Parameters 

hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 

pszlSize (PSIZEL) - points to the variable specifying the new size of the 
playground. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 
SPR_ERR_HASBACKGROUND 

Notes 

If the playground has a background bitmap, this function fails with error 
SPR_ERR_HASBACKGROUND since the two properties are mutual exclusive. 

Related information 

o HCSPLAYGROUND data type 
o CmnSprQueryPlaygroundBack 
o CmnSprQueryPlaygroundColor 
o CmnSprQueryPlaygroundSize 
o CmnSprSetPlaygroundColor 
o CmnSprSetPlaygroundSize 


═══ 13.22. CmnSprSetSpritePosition ═══

CmnSprSetSpritePosition 

Purpose 

This function sets the position of the sprite. 

Syntax 

(SPRERROR)CmnSprSetSpritePosition(hpsDraw,hsSprite,pptlNew);

Parameters 

hpsDraw (HPS) - handle of the presentation space to draw within. 

hsSprite (HCSSPRITE) - handle of the sprite instance. 

pptlNew (PPOINTL) - points to the variable specifying the new position. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 
SPR_ERR_HASNOPLAYGROUND 

Notes 

The algorithm used by this function is optimized to remove flicker when the 
bounding rectangle of the sprite at the current position overlaps the bounding 
rectangle of the sprite at the new position.  If the sprite is not visible, 
this function returns SPR_ERR_NOERROR. 

Related information 

o HCSSPRITE data type 
o CmnSprQuerySpritePosition 
o CmnSprQuerySpriteRect 
o CmnSprQuerySpriteSize 
o CmnSprQuerySpriteVisibility 
o CmnSprSetSpriteVisibility 


═══ 13.23. CmnSprSetSpriteVisibility ═══

CmnSprSetSpriteVisibility 

Purpose 

This function sets the visibility state of a sprite. 

Syntax 

(SPRERROR)CmnSprSetSpriteVisibility(hpsDraw,hsSprite,bVisible);

Parameters 

hpsDraw (HPS) - handle of the presentation space to draw within. 

hsSprite (HCSSPRITE) - handle of the sprite instance. 

bVisible (BOOL) - specifies the new visibility state. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 
SPR_ERR_HASNOPLAYGROUND 

Related information 

o HCSSPRITE data type 
o CmnSprQuerySpritePosition 
o CmnSprQuerySpriteRect 
o CmnSprQuerySpriteSize 
o CmnSprQuerySpriteVisibility 
o CmnSprSetSpritePosition 


═══ 13.24. CmnSprSetUpdateFlag ═══

CmnSprSetUpdateFlag 

Purpose 

This function sets the update flag of the playground. 

Syntax 

(SPRERROR)CmnSprSetUpdateFlag(hpgPlay,bUpdate);

Parameters 

hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 

bUpdate (BOOL) - specifies the new update flag value. 

Returns 

This function returns one of the following values: 

SPR_ERR_NOERROR 
SPR_ERR_BADHANDLE 

Notes 

The update flag determines if any drawing actually takes place when any of the 
functions requiring a presentation space handle are called. 

Related information 

o HCSPLAYGROUND data type 
o CmnSprQueryUpdateFlag 


═══ 14. String routines ═══

The purpose of this group is to provide functions that manipulate strings which 
and are not provided by the C run time library. 

Listed below are the functions which comprise this group: 

o CmnStrConvertToNumber 
o CmnStrPadString 
o CmnStrParseCommandLine 
o CmnStrParseLine 
o CmnStrQueryWord 
o CmnStrQueryWordCount 
o CmnStrQueryWordLength 
o CmnStrQueryWordPosition 
o CmnStrStripSpace 


═══ 14.1. CmnStrConvertToNumber ═══

CmnStrConvertToNumber 

Purpose 

This function converts a string into its numerical equivalent. 

Syntax 

(BOOL)CmnStrConvertToNumber(pchString,pvResult,usType);

Parameters 

pchString (PCHAR) - points to the string to convert. 

pvResult (PVOID) - points to the buffer to receive the result. The size of this 
buffer depends on the SCTN_TYPE_ constant specified. 

usType (USHORT) - specifies a combination of one SCTN_TYPE_ constant and one 
SCTN_ATTR_ constant. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnStrConvertToNumber to convert a string to a number.  This is preferable 
to atoi (atol, etc.) because this function returns a definitive indicator of 
success, whereas the ANSI functions simply return 0 when an error occurs (and 
this could be a valid value as well). 

Related information 

o SCTN_ constants 


═══ 14.2. CmnStrPadString ═══

CmnStrPadString 

Purpose 

This function pads a string with a specified character. 

Syntax 

(BOOL)CmnStrPadString(pchString,usSide,usLength,chPad);

Parameters 

pchString (PCHAR) - points to the string to pad. 

usSide (USHORT) - specifies the side to pad on as an SPS_ constant. 

usLength (USHORT) - specifies the desired length of the string. 

chPad (CHAR) - specifies the character to pad with. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnStrPadString to pad a string to a specified length. 

Related information 

o SPS_ constants 


═══ 14.3. CmnStrParseCommandLine ═══

CmnStrParseCommandLine 

Purpose 

This function parses the command line arguments. 

Syntax 

(BOOL)CmnStrParseCommandLine(ppchArgs,
                             usNumArgs,
                             pccdFormat,
                             usNumSwitches,
                             pfnError,
                             pvData);

Parameters 

ppchArgs (PCHAR *) - points to an array of pointers to the command line 
arguments. 

usNumArgs (USHORT) - specifies the number of arguments pointed to by ppchArgs. 

pccdFormat (PCSCMDDESC) - points to an array of CSCMDDESC structures describing 
the valid command line arguments. 

usNumSwitches (USHORT) - specifies the number of structures pointed to by 
pccdFormat. 

pfnError (PFNCMDERR) - points to a function which is called when an error 
occurs. 

pvData (PVOID) - points to application-specific data which is passed to the 
callback function as the fourth parameter. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnStrParseCommandLine to parse the command line arguments passed to the 
application.  For each argument that is described in pccdFormat, the 
corresponding function is called with the arguments to the command line 
argument (if any). 

pfnError is called whenever an error occurs while processing the command line. 
While this could be a syntax error (returned by the argument processing 
function), it could also be another error type (out of memory, etc.). 

Related information 

o CSCMDDESC data type 
o PFNCMDERR function 


═══ 14.4. CmnStrParseLine ═══

CmnStrParseLine 

Purpose 

This function parses a line of data containing fixed position, fixed length 
fields. 

Syntax 

(SHORT)CmnStrParseLine(pchLine,acFormat,usNumRecs,pbBuf);

Parameters 

pchLine (PCHAR) - points to the line to parse. 

pcFormat (PCSLINEDESC) - points to an array of CSLINEDESC structures describing 
the fields in the line.  On return, the usType field indicates whether or not 
the field was empty. 

usNumRecs (USHORT) - specifies the number of structures pointed to by pcFormat. 

pbBuf (PBYTE) - points to the buffer to receive the results. On return, the 
buffer is initialized to the native equivalents of the fields (numeric, string, 
etc.). 

Returns 

This function returns the number of fields successfully parsed, or SPL_ERROR if 
an error occurred. 

Notes 

Use CmnStrParseLine to parse a line consisting of fixed position, fixed length 
fields similar to the sscanf function.  For example, supposing pchLine points 
to the following data: 

12345This is a string678.90

Also, pcFormat points to four CSLINEDESC structures, containing the following 
values: 

{
   {
      0,
      5,
      SPL_TYPE_LONG
   },
   {
      21,
      6,
      SPL_TYPE_FLOAT
   },
   {
      5,
      16,
      SPL_TYPE_STRING
   },
   {
      28,
      4,
      SPL_TYPE_BYTE
   }
}
pbBuf points to a structure defined as follows: 

typedef struct {
   LONG lField1;
   float fField2;
   CHAR achField3[17];
   BYTE bField4;
} BUF, FAR *PBUF;

On exit, pbBuf points to the initialized structure containing 12345, 678.9, 
"This is a string", and (undefined), and the usType field of the CSLINEDESC 
structures will be SPL_FOUND, SPL_FOUND, SPL_FOUND, and SPL_NOT_FOUND (to 
indicate that there was not fourth field). 

It is imperative to note that if you are using this function, all structures 
initialized by this function must be "unaligned", i.e. no alignment of fields 
should be done by the compiler.  If you forget to specify this, unpredictable 
results will occur. 

Related information 

o SPL_ constants 
o CSLINEDESC data type 


═══ 14.5. CmnStrQueryWord ═══

CmnStrQueryWord 

Purpose 

This function returns the specified word in a string. 

Syntax 

(BOOL)CmnStrQueryWord(pchLine,sWord,pchWord,usSzWord);

Parameters 

pchLine (PCHAR) - points to the line to retrieve the word from. 

sWord (SHORT) - specifies the 0-based word number to retrieve. 

pchWord (PCHAR) - points to the buffer to receive the result. On return, the 
buffer contains the word retrieved. 

usSzWord (USHORT) - specifies the size of the buffer pointed to by pchWord. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnStrQueryWord to retrieve a word from a line.  A word is defined as a 
sequence of letters, digits, and/or punctuation, delimited by whitespace. 

Related information 

o CmnStrQueryWordCount 
o CmnStrQueryWordLength 
o CmnStrQueryWordPosition 


═══ 14.6. CmnStrQueryWordCount ═══

CmnStrQueryWordCount 

Purpose 

This function queries the number of words in a line. 

Syntax 

(USHORT)CmnStrQueryWordCount(pchLine);

Parameters 

pchLine (PCHAR) - points to the line to query. 

Returns 

This function returns the number of words in the specified line. 

Notes 

Use CmnStrQueryWordCount to query the number of words in a line of ASCII data. 

Related information 

o CmnStrQueryWord 
o CmnStrQueryWordLength 
o CmnStrQueryWordPosition 


═══ 14.7. CmnStrQueryWordLength ═══

CmnStrQueryWordLength 

Purpose 

This function queries the length of a specified word in a line. 

Syntax 

(SHORT)CmnStrQueryWordLength(pchLine,sWord);

Parameters 

pchLine (PCHAR) - points to the line to query. 

sWord (SHORT) - specifies the number of the word to query. 

Returns 

This function returns the length of the specified word. 

Notes 

Use CmnStrQueryWordLength to query the length of a specified word in a line of 
ASCII data. 

Related information 

o CmnStrQueryWord 
o CmnStrQueryWordCount 
o CmnStrQueryWordPosition 


═══ 14.8. CmnStrQueryWordPosition ═══

CmnStrQueryWordPosition 

Purpose 

This function queries the position of a specified word in a line. 

Syntax 

(SHORT)CmnStrQueryWordPosition(pchLine,sWord);

Parameters 

pchLine (PCHAR) - points to the line to query. 

sWord (SHORT) - specifies the number of the word to query. 

Returns 

This function returns the 0-based index of the beginning of the specified word 
in the line. 

Notes 

Use CmnStrQueryWordPosition to query the position of a word in a line of ASCII 
data. 

Related information 

o CmnStrQueryWord 
o CmnStrQueryWordCount 
o CmnStrQueryWordLength 


═══ 14.9. CmnStrStripSpace ═══

CmnStrStripSpace 

Purpose 

This function strips the whitespace from the beginning and/or the end of a 
string. 

Syntax 

(BOOL)CmnStrStripSpace(pchString,usOptions);

Parameters 

pchString (PCHAR) - points to the string to strip. 

usOptions (USHORT) - specifies the side to strip from as an SPS_ constant. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnStrStripSpace to strip the white space from a string. 

Related information 

o SPS_ constants 


═══ 15. Screen I/O routines ═══

The purpose of this group is to provide miscellaneous text-mode functions. 

Listed below are the functions which comprise this group: 

o CmnVioDisplayMessage 
o CmnVioGetString 
o CmnVioLoadMessage 


═══ 15.1. CmnVioDisplayMessage ═══

CmnVioDisplayMessage 

Purpose 

This function loads a message from a message file and writes it to stderr. 

Syntax 

(BOOL)CmnVioDisplayMessage(pchMsgFile,ulId,...);

Parameters 

pchMsgFile (PCHAR) - points to the name of the message file. Even if the 
message file is bound to the executable, this must be the name of the original 
message file. 

ulId (ULONG) - specifies the identifier of the message to load. 

... (va_list) - specifies any additional arguments referred to by the message. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnVioDisplayMessage to load and display a message from the specified 
message file.  Note that while fprintf will allow fields whose descriptors 
begin with a width specifier (e.g. "%05d%cdq.), this function does not since 
DosGetMessage attempts to substitute positional parameters when it encounters 
this. 


═══ 15.2. CmnVioGetString ═══

CmnVioLoadMessage 

Purpose 

This function gets a string from the user. 

Syntax 

(BOOL)CmnVioGetString(pchBuf,ulSzBuf,ulOptions);

Parameters 

pchBuf (PCHAR) - points to the buffer to hold the result.  On return, the 
buffer contains the string. 

ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pchBuf. 

ulOptions (ULONG) - one or more VGS_* constants. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnVioGetString to get a string from the user.  The advantage of using this 
function instead of a C library function is that this function provides the 
following: 

o Cursor movement via left, right, Ctrl-left (word-left), Ctrl-right 
  (word-right). 

o Erase contents via Escape key. 

o Options for unreadable entry and input required. 

Related information 

o VGS_ constants 


═══ 15.3. CmnVioLoadMessage ═══

CmnVioLoadMessage 

Purpose 

This function loads a message from a message file. 

Syntax 

(BOOL)CmnVioLoadMessage(pchMsgFile,ulId,pchBuf,ulSzBuf);

Parameters 

pchMsgFile (PCHAR) - points to the name of the message file. Even if the 
message file is bound to the executable, this must be the name of the original 
message file. 

ulId (ULONG) - specifies the identifier of the message to load. 

pchBuf (PCHAR) - points to the buffer to receive the result. On return, the 
buffer contains the loaded message. 

ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pchBuf. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnVioLoadMessage to load a message from the specified message file.  Note 
that it is impossible to have a message with simply a carriage-return at the 
end (versus a carriage-return, line-feed pair), since the toolkit utility 
MKMSGF indicates this to be a syntax error. 


═══ 16. Windowing routines ═══

The purpose of this group is to provide miscellaneous windowing functions. 

Listed below are the functions which comprise this group: 

o CmnWinCenterWindow 
o CmnWinDisplayMessage 
o CmnWinRestorePosition 
o CmnWinRestorePosFromBuffer 
o CmnWinSavePosition 
o CmnWinSavePosToBuffer 


═══ 16.1. CmnWinCenterWindow ═══

CmnWinCenterWindow 

Purpose 

This function centers a window within its parent. 

Syntax 

(VOID)CmnWinCenterWindow(hwndCenter);

Parameters 

hwndCenter (HWND) - specifies the handle of the window to center. 

Notes 

Use CmnWinCenterWindow to center a window within its parent. 


═══ 16.2. CmnWinDisplayMessage ═══

CmnWinDisplayMessage 

Purpose 

This function loads a message from the STRINGTABLE and displays it in a message 
box. 

Syntax 

(SHORT)CmnWinDisplayMessage(hwndParent,
                            hwndOwner,
                            ulStyle,
                            hmDll,
                            usId,
                            usHelpId,
                            ...);

Parameters 

hwndParent (HWND) - specifies the handle of the parent window. 

hwndOwner (HWND) - specifies the handle of the owner window. 

ulStyle (ULONG) - specifies the style of the message box.  If 0 is specified, 
MB_INFORMATION | MB_OK is used. 

hmDll (HMODULE) - specifies the handle to the module containing the STRINGTABLE 
to load from (or NULL if the .EXE file contains the STRINGTABLE). 

usId (USHORT) - specifies the identifier of the message to load. 

usHelpId (USHORT) - specifies the identifier that is used when calling the help 
hook.  If this is 0, no help button is shown in the message box. 

... (va_list) - specifies any additional arguments referred to by the message. 

Returns 

This function returns the same result as WinMessageBox. 

Notes 

Use CmnWinDisplayMessage to load a message and display it on the screen. 


═══ 16.3. CmnWinRestorePosition ═══

CmnWinRestorePosition 

Purpose 

This function restores the position of a window previously saved with 
CmnWinSavePosition. 

Syntax 

(BOOL)CmnWinRestorePosition(hwndWindow,
                            hiniProfile,
                            pchAppl,
                            pchKey);

Parameters 

hwndWindow (HWND) - specifies the handle of the window to restore. 

hiniProfile (HINI) - specifies the .INI file handle containing the saved 
position information. 

pchAppl (PCHAR) - points to the application name that the positional 
information was saved under. 

pchKey (PCHAR) - points to the key name that the positional information was 
saved under. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnWinRestorePosition to restore the position of a window previously saved 
with CmnWinSavePosition.  For MDI applications, you should use the 
CmnWinSavePosToBuffer and CmnWinRestorePosFromBuffer function. 

Related information 

o CmnWinSavePosition 


═══ 16.4. CmnWinRestorePosFromBuffer ═══

CmnWinRestorePosFromBuffer 

Purpose 

This function restores the position of a window previously saved with 
CmnWinSavePosToBuffer. 

Syntax 

BOOL CmnWinRestorePosFromBuffer(hwndWindow,pcpPosition);

Parameters 

hwndWindow (HWND) - the handle of the window to restore 

pcpPosition (PCWPOSITION) - points to the variable containing the information 
to be used when restoring 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnWinRestorePosFromBuffer to restore a window's size and position from the 
information saved by CmnWinSavePosToBuffer. 

Related information 

o CWPOSITION data type 
o CmnWinSavePosToBuffer 


═══ 16.5. CmnWinSavePosition ═══

CmnWinSavePosition 

Purpose 

This function saves the position of a window to be restored later with 
CmnWinRestorePosition. 

Syntax 

(BOOL)CmnWinSavePosition(hwndWindow,
                         hiniProfile,
                         pchAppl,
                         pchKey);

Parameters 

hwndWindow (HWND) - specifies the handle of the window to restore. 

hiniProfile (HINI) - specifies the .INI file handle to which the saved position 
information will be written. 

pchAppl (PCHAR) - points to the application name that the positional 
information will be saved under. 

pchKey (PCHAR) - points to the key name that the positional information will be 
saved under. 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnWinSavePosition to save the current size and position of the specified 
window for restoration at a later time. 

Related information 

o CmnWinRestorePosition 


═══ 16.6. CmnWinSavePosToBuffer ═══

CmnWinSavePosToBuffer 

Purpose 

This function saves the position of a window to a buffer for later use with 
CmnWinRestorePosFromBuffer. 

Syntax 

BOOL CmnWinSavePosToBuffer(hwndWindow,pcpPosition);

Parameters 

hwndWindow (HWND) - the handle of the window to restore 

pcpPosition (PCWPOSITION) - points to the variable to contain the information 
to be used when restoring 

Returns 

This function returns TRUE if successful, or FALSE otherwise. 

Notes 

Use CmnWinSavePosToBuffer to save a window's size and position so that it can 
be later restored using CmnWinRestorePosFromBuffer. 

Related information 

o CWPOSITION data type 
o CmnWinRestorePosFromBuffer 


═══ <hidden>  ═══

Constant                      Meaning 
CCI_TYPE_CLIENT               Specifies that the connection type is (to be) 
                              client. 
CCI_TYPE_SERVER               Specifies that the connection type is (to be) 
                              server. 
CCI_TYPE_SERVERCONNECT        Specifies that the connection type is a server 
                              data connection to a client.  This can never be 
                              specified for CmnComOpenConnection. 
CCI_TYPE_CLIENTSERVER         Specifies that the connection type is (to be) 
                              client or server. 
CCI_ATTR_NOACKS               Specifies that no acknowledgements are to be 
                              requested by CmnComWriteData.  This is useful for 
                              eliminating overhead for transaction-based 
                              protocols where the applications must implement 
                              their own acknowledgements. 


═══ <hidden>  ═══

Constant                      Meaning 
CSC_CLOSE                     specifies that the connection should be closed. 
CSC_RESET                     specifies that the connection should be reset. 
                              "Reset" is an abstract term that is defined by 
                              the application. 


═══ <hidden>  ═══

A 32-bit handle used to specify a connection.  This handle is created by either 
CmnComOpenConnection or CmnComWaitConnection and is destroyed by 
CmnComCloseConnection. 

Related information 

o CmnComCloseConnection 
o CmnComOpenConnection 
o CmnComWaitConnection 


═══ <hidden>  ═══

typedef struct _CCOPENINFO {
   CHAR achMachine[MAX_CONNECTNAME+1];
   CHAR achConnect[MAX_CONNECTNAME+1];
   USHORT usAttr;
   LONG lTimeout;
} CCOPENINFO, FAR *PCCOPENINFO;

achMachine                    Specifies the name of the remote machine to 
                              connect to.  If this is an empty string, the 
                              connection is created locally. 
achConnect                    Specifies the name of the connection. 
usAttr                        Specifies a CCI_TYPE_* constant and zero or more 
                              CCI_ATTR_* constants. 
lTimeout                      Specifies the timeout, in seconds, for 
                              connections, data reading, and acknowledgement 
                              waiting. If this value is CCI_ATTR_NOTIMEOUT, no 
                              timeout will occur. 

Related information 

o CCI_ constants 


═══ <hidden>  ═══

typedef struct _CCCONNECTINFO {
   CHAR achConnect[MAX_CONNECTNAME+1];
   USHORT usAttr;
   ULONG ulSzData;
   LONG lTimeout;
} CCCONNECTINFO, FAR *PCCCONNECTINFO;

achConnect                    Specifies the fully qualified name of the 
                              connection.  For clients, this will not be the 
                              name of the connection specified in the 
                              CCOPENINFO structure on the call to 
                              CmnComOpenConnection. 
usAttr                        Specifies the type of the connection and any 
                              associated attributes.  These are defined as CCI_ 
                              constants. 
ulSzData                      Specifies the size, in bytes, of any data waiting 
                              to be read.  This is the same value that is 
                              returned by CmnComQueryData. 
lTimeout                      Specifies the timeout value, in seconds. 

For calls to CmnSetHandleInfo, lTimeout is the only field that is used.  All 
others are ignored. 

Related information 

o CCI_ constants 
o CmnSetHandleInfo 
o CmnComOpenConnection 
o CmnComQueryData 


═══ <hidden>  ═══

Constant                      Meaning 
DWT_TYPE_NAME                 specifies that the file argument points to the 
                              file name 
DWT_TYPE_FILE                 specifies that the file argument points to a FILE 
                              structure 


═══ <hidden>  ═══

Constant                      Meaning 
FCS_ATTR_NORMAL               specifies normal files 
FCS_ATTR_READONLY             specifies read-only files 
FCS_ATTR_HIDDEN               specifies hidden files 
FCS_ATTR_SYSTEM               specifies system files 
FCS_ATTR_DIRECTORY            specifies directories 
FCS_ATTR_ARCHIVED             specifies archived files 


═══ <hidden>  ═══

Constant                      Meaning 
FEA_TYPE                      specifes the "Type" extended attribute 
FEA_KEYPHRASES                specifes the "Key phrases" extended attribute 
FEA_SUBJECT                   specifes the "Subject" extended attribute 
FEA_COMMENTS                  specifes the "Comments" extended attribute 
FEA_HISTORY                   specifes the "History" extended attribute 
FEA_VERSION                   specifes the "Version" extended attribute 
FEA_ICON                      specifes the "Icon" extended attribute 
FEA_ASSOCTABLE                specifes the "Assoctable" extended attribute 
FEA_HPFSNAME                  specifes the "HPFS name" extended attribute 


═══ <hidden>  ═══

Constant                      Meaning 
FCD_OPT_WANTFORMATTED         specifies that the function should fail if the 
                              destination diskette is not already formatted. 
                              If this option is not specified, and the 
                              destination diskette is not formatted, 
                              CmnFilFormatDiskette is called to format the 
                              diskette. 

Related information 

o CmnFilFormatDiskette 


═══ <hidden>  ═══

Constant                      Meaning 
FCD_TYPE_ERROR                specifies that the value of the second parameter 
                              of pfnCallback is an FCD_ERR_* constant. 
FCD_TYPE_MESSAGE              specifies that the value of the second parameter 
                              of pfnCallback is an FCD_MSG_* constant.  The 
                              return value of pfnCallback is determined by this 
                              FCD_MSG_* constant. 
FCD_TYPE_PROGRESS             specifies that the value of the second parameter 
                              of pfnCallback is a number in the range 0-100 
                              which specifies the percentage complete of the 
                              current operation (read, write, etc.). 


═══ <hidden>  ═══

Constant                      Meaning 
FCD_MSG_BEGINFORMAT           specifies that the format operation is beginning. 
FCD_MSG_BEGINREAD             specifies that the read of the source diskette is 
                              beginning. 
FCD_MSG_BEGINVERIFY           specifies that the verify of the destination 
                              diskette is beginning. 
FCD_MSG_BEGINWRITE            specifies that the write of the destination 
                              diskette is beginning. 
FCD_MSG_ENDFORMAT             specifies that the format operation has completed 
                              successfully. 
FCD_MSG_ENDREAD               specifies that the source diskette was 
                              successfully read. 
FCD_MSG_ENDVERIFY             specifies that the destination diskette was 
                              successfully verified. 
FCD_MSG_ENDWRITE              specifies that the destination diskette was 
                              successfully written. 
FCD_MSG_SIZEMISMATCH          specifies that the source and destination 
                              diskette sizes do not match. pfnCallback should 
                              return TRUE if a new diskette has been inserted 
                              and the operation should be retried or FALSE if 
                              the copy operation should be halted. 
FCD_MSG_VALIDATESRCDISK       specifies that pfnCallback should verify that the 
                              source diskette is the desired one to be copied. 
                              This is usually done by calling CmnFilQueryLabel 
                              to check the diskette label. pfnCallback should 
                              return TRUE if the correct diskette is in the 
                              drive or FALSE otherwise.  Returning FALSE causes 
                              CmnFilCopyDiskette to resend the 
                              FCD_MSG_WANTSRCDISK message. 
FCD_MSG_WANTDESTDISK          specifies that the destination diskette should be 
                              inserted in the drive. This is sent if the source 
                              and destination drives are the same and the 
                              source diskette was successfully read or if there 
                              is no diskette in the destination drive. 
                              pfnCallback should return TRUE if the diskette 
                              has been inserted and the operation should be 
                              retried or FALSE if the copy operation should be 
                              halted. 
FCD_MSG_WANTFORMATDISK        specifies that the diskette to be formatted 
                              should be inserted in the drive.  pfnCallback 
                              should return TRUE if the diskette has been 
                              inserted and the operation should be retried or 
                              FALSE if the format operation should be halted. 
FCD_MSG_WANTSRCDISK           specifies that the source diskette should be 
                              inserted in the drive.  This is sent if there is 
                              no diskette in the destination drive. pfnCallback 
                              should return TRUE if the diskette has been 
                              inserted and the operation should be retried or 
                              FALSE if the copy operation should be halted. 
FCD_MSG_WRITEPROTECTED        specifies that the destination diskette is 
                              write-protected. pfnCallback should return TRUE 
                              if this condition has been corrected and the 
                              operation should be retried or FALSE if the copy 
                              operation should be halted. 


═══ <hidden>  ═══

Constant                      Meaning 
FCD_ERR_ABORTED               specifies that the operation was halted because 
                              pfnCallback returned FALSE for an FCD_MSG_* 
                              constant whose return value is significant. 
FCD_ERR_CLOSEFAILED           specifies that an attempt to close the diskette 
                              failed. 
FCD_ERR_DESTDRVINVALID        specifies that the destination drive specified 
                              does not support removable media. 
FCD_ERR_FORMATFAILED          specifies that the format operation failed. 
FCD_ERR_LOCKFAILED            specifies that either the source or destination 
                              drive could not be "locked". 
FCD_ERR_NOMEMORY              specifies that there is not enough memory to hold 
                              the contents of the source diskette. 
FCD_ERR_OPENFAILED            specifies that an attempt to open the diskette 
                              failed. 
FCD_ERR_READFAILED            specifies that a read operation failed. 
FCD_ERR_SRCDRVINVALID         specifies that the source drive specified does 
                              not support removable media. 
FCD_ERR_UNLOCKFAILED          specifies that either the source or destination 
                              drive could not be "unlocked". 
FCD_ERR_VERIFYFAILED          specifies that the verify operation failed. 
FCD_ERR_WRITEFAILED           specifies that a write operation failed. 


═══ <hidden>  ═══

A 32-bit handle used for file searches.  It is created using the function 
CmnFilCreateSearch and is destroyed using the function CmnFilDestroySearch. 

Related information 

o CmnFilCreateSearch 
o CmnFilDestroySearch 


═══ <hidden>  ═══

Constant                      Meaning 
CFFI_SECTOR_128B              specifies 128 bytes per sector 
CFFI_SECTOR_256B              specifies 256 bytes per sector 
CFFI_SECTOR_512B              specifies 512 bytes per sector 
CFFI_SECTOR_1024B             specifies 1024 bytes per sector 


═══ <hidden>  ═══

Format parameters 

typedef struct _CFFORMATINFO {
   ULONG ulSzStruct;
   ULONG ulNumTracks;
   ULONG ulNumSectors;
   ULONG ulSzSector;
} CFFORMATINFO, *PCFFORMATINFO;

ulSzStruct                    specifies the size of the structure in bytes. 
ulNumTracks                   specifies the desired number of tracks. 
ulNumSectors                  specifies the number of sectors per track. 
ulSzSector                    specifies a CFFI_SECTOR_* constant describing the 
                              size of each sector. 

Standard formats are listed below: 

360 KB (5.25 inch)            ulNumTracks=40, ulNumSectors=9, 
                              ulSzSector=CFFI_SECTOR_512B 
720 KB (3.5 inch)             ulNumTracks=80, ulNumSectors=9, 
                              ulSzSector=CFFI_SECTOR_512B 
1.2 MB (5.25 inch)            ulNumTracks=80, ulNumSectors=15, 
                              ulSzSector=CFFI_SECTOR_512B 
1.44 MB (3.5 inch)            ulNumTracks=80, ulNumSectors=18, 
                              ulSzSector=CFFI_SECTOR_512B 
2.88 MB (3.5 inch)            ulNumTracks=80, ulNumSectors=36, 
                              ulSzSector=CFFI_SECTOR_512B 

It is recommended that your application use a standard format since unexpected 
results may occur otherwise (due to limitations in the file system drivers 
and/or hardware). 

Related information 

o CFFI_SECTOR_ constants 


═══ <hidden>  ═══

typedef BOOL (* EXPENTRY PFNDISKIO)(ULONG,ULONG,PVOID);

Input 

ULONG               specifies an FCD_TYPE_* constant which describes how the 
                    next parameter is to be interpreted. 
ULONG               depending on the value of the last parameter: 

   FCD_TYPE_PROGRESS   specifies a value in the range 0-100 which specifies the 
                       progress of the copy operation. 
   FCD_TYPE_MESSAGE    specifies an FCD_MSG_* constant. 
   FCD_TYPE_ERROR      specifies an FCD_ERR_* constant. 
PVOID               specifies the user data passed to the CmnFilCopyDiskette 
                    function. 

For FCF_TYPE_PROGRESS, this function returns TRUE if the operation is to 
continue, or FALSE if the operation is to be halted.  For FCD_TYPE_MESSAGE, the 
return value may or may not be significant, depending on the specific FCD_MSG_* 
constant passed. 

Related information 

o FCD_TYPE_ constants 
o FCD_MSG_ constants 
o FCD_ERR_ constants 


═══ <hidden>  ═══

Constant                      Meaning 
LAR_TAIL                      specifies that the record should be inserted at 
                              the end of the list. 
LAR_HEAD                      specifies that the record should be inserted at 
                              the beginning of the list. 


═══ <hidden>  ═══

Constant                      Meaning 
LQR_END                       specifies that the last record should be returned 
LQR_PREVIOUS                  specifies that the previous record should be 
                              returned 
LQR_NEXT                      specifies that the next record should be returned 


═══ <hidden>  ═══

A 32-bit handle used to specify a linked list.  It is created using the 
function CmnLstCreateList and is destroyed using the function 
CmnLstDestroyList. 

Related information 

o CmnLstCreateList 
o CmnLstDestroyList 


═══ <hidden>  ═══

typedef struct _CLLISTINFO {
   USHORT usSzRecord;
   USHORT usNumRecords;
   PVOID pvHead;
   PVOID pvTail;
} CLLISTINFO, FAR *PCLLISTINFO;

usSzRecord                    Contains the size of each record in the list. 
usNumRecords                  Contains the number of records currently in the 
                              list. 
pvHead                        Points to the head of the list. 
pvTail                        Points to the tail of the list. 


═══ <hidden>  ═══

typedef SHORT (* EXPENTRY PFNRECCOMP)(PVOID,PVOID,PVOID);
//-------------------------------------------------------------------------
// SHORT EXPENTRY pfnRecComp(PVOID pvFirst,PVOID pvSecond,PVOID pvData);
//-------------------------------------------------------------------------

Input 

pvFirst (PVOID)     Points to the first record to be compared 
pvSecond (PVOID)    Points to the second record to be compared 
pvData (PVOID)      Points to application-defined data 

Returns 

-1                  If the first parameter is "less than" the second parameter 
0                   If the first parameter is "equal to" the second parameter 
1                   If the first parameter is "greater than" the second 
                    parameter 


═══ <hidden>  ═══

typedef VOID (* EXPENTRY PFNRECFUNC)(PVOID,PVOID);
//-------------------------------------------------------------------------
// SHORT EXPENTRY pfnRecFunc(PVOID pvRecord,PVOID pvData);
//-------------------------------------------------------------------------

Input 

pvRecord (PVOID)    Points to a record in the list 
pvData (PVOID)      Points to application-defined data 


═══ <hidden>  ═══

typedef BOOL (* EXPENTRY PFNRECMED)(HCLLIST,PVOID,PVOID);
//-------------------------------------------------------------------------
// SHORT EXPENTRY pfnRecMed(HCLLIST hclSubList,PVOID pvBuffer,PVOID pvData);
//-------------------------------------------------------------------------

Input 

hclSubList (HCLLIST) Handle to the list to find the median of 
pvBuffer (PVOID)    Points to a buffer large enough to hold a single record 
pvData (PVOID)      Points to application-defined data 

Output 

pvBuffer (PVOID)    Points to a buffer containing the median of the specified 
                    list 

Returns 

TRUE if successful, FALSE otherwise 


═══ <hidden>  ═══

A 32-bit handle used to specify a memory manager instance.  it is created using 
the function CmnMemInitialize and is destroyed using the function 
CmnMemTerminate. 

Related information 

o CmnMemInitialize 
o CmnMemTerminate 


═══ <hidden>  ═══

typedef struct _CMMEMINFO {
   USHORT usNumHeaps;
   ULONG ulSzHeap;
   ULONG ulMemUsed;
} CMMEMINFO, FAR *PCMMEMINFO;

usNumHeaps                    Contains the number of internal heaps to be used 
                              by the memory management routines.  The default 
                              is 256. 
ulSzHeaps                     Contains the size of each heap.  The default is 
                              61440. 
ulMemUsed                     Contains the amount of memory currently allocated 
                              by this memory handle. This field is ignored by 
                              CmnMemInitialize(). 


═══ <hidden>  ═══

A 32-bit handle used to specify an object manager instance.  it is created 
using the function CmnObjInitialize and is destroyed using the function 
CmnObjTerminate. 

Related information 

o CmnObjInitialize 
o CmnObjTerminate 


═══ <hidden>  ═══

typedef struct _COOBJECTINFO {
   HCOOBJECT hcoParent;
   CHAR achName[MAX_OBJECTNAME+1];
   ULONG ulSzData;
   PVOID pvData;
   USHORT usNumChildren;
   ULONG ulReserved;
} COOBJECTINFO, FAR *PCOOBJECTINFO;

hcoParent                     Specifies the handle of the parent object.  If 
                              NULL then this is the root object. 
achName                       Specifies the fully qualified name of the object. 
ulSzData                      Specifies the size of the object-data. 
pvData                        Points to the object-data.  Using this field is 
                              discouraged, since this points to the 
                              object-manager's copy of the data.  Instead, use 
                              the CmnObjQueryObjectData function. 
usNumChildren                 Specifies the number of immediate children. 
ulReserved                    Reserved, though it might not be zero. 

Related information 

o CmnObjQueryObjectData 


═══ <hidden>  ═══

A 32-bit handle used to specify a set.  It is created using the function 
CmnSetCreateSet and is destroyed using the function CmnSetDestroySet. 

Related information 

o CmnSetCreateSet 
o CmnSetDestroySet 


═══ <hidden>  ═══

typedef struct _CSSETINFO {
   ULONG ulMaxElements;
   ULONG ulElementsSet;
} CSSETINFO, FAR *PCSSETINFO;

ulMaxElements                 specifies the size of the set 
ulElementsSet                 specifies the number of elements currently set in 
                              the set 


═══ <hidden>  ═══

Constant                      Meaning 
SWS_TIMEOUT_IMMEDIATE         specifies that the function should return 
                              immediately if the condition fails 
SWS_TIMEOUT_NEVER             specifies that the function should never return 
                              until the condition is met 


═══ <hidden>  ═══

A 32-bit handle used to specify a signal.  It is created using the function 
CmnSigCreateSignal and is destroyed using the function CmnSigDestroySignal. 

Related information 

o CmnSigCreateSignal 
o CmnSigDestroySignal 


═══ <hidden>  ═══

A 32-bit handle used to specify a signal list.  It is created using the 
function CmnSigCreateSignalList and is destroyed using the function 
CmnSigDestroySignalList. 

Related information 

o CmnSigCreateSignalList 
o CmnSigDestroySignalList 


═══ <hidden>  ═══

A 32-bit handle used to specify a playground instance.  This is created by the 
CmnSprCreatePlayground function and is destroyed by the CmnSprDestroyPlayground 
function.  Sprites must be added to a playground before they can be manipulated 
in any way. 

Related information 

o CmnSprAddSprite 
o CmnSprCreatePlayground 
o CmnSprDestroyPlayground 
o CmnSprRemoveSprite 


═══ <hidden>  ═══

A 32-bit handle used to specify a sprite instance.  This is created by the 
CmnSprCreateSprite function and is destroyed by the CmnSprDestroySprite 
function.  Sprites must be added to a playground before they can be manipulated 
in any way. 

Related information 

o CmnSprAddSprite 
o CmnSprCreateSprite 
o CmnSprDestroySprite 
o CmnSprRemoveSprite 


═══ <hidden>  ═══

Constant                      Meaning 
SCTN_TYPE_BYTE                specifies that the ASCII data represents a byte 
                              of data 
SCTN_TYPE_SHORT               specifies that the ASCII data represents a short 
                              integer (2 bytes) 
SCTN_TYPE_LONG                specifies that the ASCII data represents a long 
                              integer (4 bytes) 
SCTN_TYPE_FLOAT               specifies that the ASCII data represents a 
                              single-precision floating point number 
SCTN_TYPE_DOUBLE              specifies that the ASCII data represents a 
                              double-precision floating point number 

The following are attribute constants which can be or'd with the above type 
constants. 

Constant                      Meaning 
SCTN_ATTR_DECIMAL             specifies that the number represented in ASCII is 
                              in decimal 
SCTN_ATTR_HEX                 specifies that the number represented in ASCII is 
                              in hexadecimal 


═══ <hidden>  ═══

Constant                      Meaning 
SPL_TYPE_BYTE                 specifies that the field represents a byte of 
                              data 
SPL_TYPE_CHAR                 specifies that the field represents a character 
                              of data 
SPL_TYPE_STRING               specifies that the field represents a string of 
                              characters.  Note that the length of the field 
                              does not include the terminating `\0'. 
SPL_TYPE_SHORT                specifies that the field represents a short 
                              integer (2 bytes) 
SPL_TYPE_LONG                 specifies that the field represents a long 
                              integer (4 bytes) 
SPL_TYPE_FLOAT                specifies that the field represents a 
                              single-precision floating point number 
SPL_TYPE_DOUBLE               specifies that the field represents a 
                              double-precision floating point number 
SPL_TYPE_RESERVED             specifies that the bytes in the destination 
                              buffer are to be skipped 

The following are attribute constants which can be or'd with the numeric type 
constants listed above. 

Constant                      Meaning 
SPL_ATTR_DECIMAL              specifies that the number represented in ASCII is 
                              in decimal 
SPL_ATTR_HEX                  specifies that the number represented in ASCII is 
                              in hexadecimal 

Return code values are the following: 

Constant                      Meaning 
SPL_NOTFOUND                  specifies that the field was empty 
SPL_FOUND                     specifies that the field was not empty 


═══ <hidden>  ═══

Constant                      Meaning 
SPS_LEFT                      Specifies that the string is to be padded on the 
                              left side. 
SPS_RIGHT                     Specifies that the string is to be padded on the 
                              right side. 


═══ <hidden>  ═══

Command line argument descriptor 

typedef struct _CSCMDDESC {
   USHORT usId;
   CHAR achSwitch[SPCL_MAX_SWITCH+1];
   USHORT usNumArgs;
   USHORT usFlags;
   PFNCMDARG pfnCallback;
} CSCMDDESC, FAR *PCSCMDDESC;

usId                          specifies the identifier for the command line 
                              argument 
achSwitch                     specifies the string representing the command 
                              line argument 
usNumArgs                     specifies the number of arguments the command 
                              line argument requires 
usFlags                       specifies a combination of SPCL_FLG_ constants 
pfnCallback                   points to a callback function (see below) 

SPCL_FLG_ constants 

SPCL_FLG_CASESENSITIVE        specifies that achSwitch is case-sensitive 
SPCL_FLG_SUBSTRING            specifies that achSwitch is a substring of the 
                              entire command line argument.  If you specify 
                              this, you must also specify SPCL_FLG_ARGCONCAT. 
SPCL_FLG_ARGCONCAT            specifies that the first argument is concatenated 
                              to the command line argument (e.g. "-FPa", where 
                              "a" is the first argument). 

PFNCMDARG function 

typedef BOOL (* EXPENTRY PFNCMDARG)(USHORT,PCHAR *,USHORT,PVOID);
//-------------------------------------------------------------------------
// VOID EXPENTRY pfnCmdArg(USHORT usId,
//                         PCHAR *apchArgs,
//                         USHORT usNumArgs,
//                         PVOID pvData);
//-------------------------------------------------------------------------

Input 

usId (USHORT)       specifies the identifier of the switch 
apchArgs (PCHAR *)  points to an array of arguments to the command line 
                    argument 
usNumArgs (USHORT)  specifies the number of arguments 
pvData (PVOID)      Pointer to application-defined data 

Returns 

TRUE if the processing was successful, or FALSE otherwise 


═══ <hidden>  ═══

typedef struct _CSLINEDESC {
   USHORT usOffset;
   USHORT usLength;
   USHORT usType;
} CSLINEDESC, FAR *PCSLINEDESC;

usOffset                      specifies the 0-based offset of the field 
usLength                      specifies the length in bytes of the field 
usType                        specifies a combination of SPL_ constants 

Related information 

o SPL_ constants 


═══ <hidden>  ═══

typedef VOID (* EXPENTRY PFNCMDERR)(USHORT,PVOID);
//-------------------------------------------------------------------------
// VOID EXPENTRY pfnCmdErr(USHORT usId,PVOID pvData);
//-------------------------------------------------------------------------

Input 

usId (USHORT)       Specifies the error code 

   SPCL_ERR_NOMEMORY   The function could not allocate a required amount of 
                       memory 
   SPCL_ERR_NOTENOUGHARGS A command-line switch did not contain enough 
                       arguments 
   SPCL_ERR_BADSWITCH  An invalid switch was specified 
   SPCL_ERR_SWITCHERROR The switch function indicated that an error occurred 
pvData (PVOID)      Pointer to application-defined data 


═══ <hidden>  ═══

Constant                      Meaning 
VGS_UNREADABLE                specifies that the input should not be readable. 
                              Each character is displayed as an asterisk ('*'). 
VGS_REQUIRED                  specifies that an empty string may not be 
                              returned. 


═══ <hidden>  ═══

typedef struct _CWPOSITION {
   ULONG ulSzStruct;
   SWP swpPosition;
   USHORT ausExtra[6];
} CWPOSITION, FAR *PCWPOSITION;

ulSzStruct                    specifies the size of the structure in bytes 
swpPosition                   specifies the current size and position 
ausExtra                      specifies the minimized position and the restored 
                              size and position