Function _conParam() | Xbase++

Returns a container handle for an Xbase++ parameter.

ContainerHandle _conParam(XppParamList pList, ULONG ulIndex,
                          BOOL *pbRef);

XppParamList pList

Pointer to Xbase++ parameter list through which the parameters are accessed.

ULONG ulIndex

Position of the parameter for which a container handle is to be returned. Parameters are numbered beginning with 1.

BOOL *pbRef

Pointer to a BOOL buffer which is set to TRUE when the parameter was passed by reference. The pointer may also be NULL. In this case the function will create a copy of the parameter even if it is passed by reference.

The function returns the container handle of a parameter. If the corresponding parameter is not passed to your function a NIL-container will be returned. The returned container handle is normally a copy which has to be freed with _conRelease(). The only exception are reference parameters. As long as pbRef is not NULL there is no new container created for parameters which are passed by reference. So for reference parameters it is not allowed to call _conRelease()! If the parameter can not be furnished due to any errors, a NULLCONTAINER is returned.

_conParam() allows access to the parameters which were passed to the C function from within the Xbase++ program. The container handle furnished by this function can be used to read and write the value of the parameter using the _conGet...() and _conPut...() functions.

Since it can not be determined later (from the container alone) whether the Xbase++ parameter was passed by reference, this information can be determined by using the additional argument pbRef. When no error occurs, after the call this buffer contains TRUE if the parameter was passed by reference and otherwise contains FALSE. If pbRef is not used (i.e. NULL) _conParam will always return a copy which has to be freed with _conRelease() even if the parameter was passed by reference. If pbRef is used you have always to check that the parameter is not passed by reference before you call _conRelease().

Splitting of an event code

#include <ctype.h>        /* isupper(), iscntrl(), tolower() */ 
#include "xpppar.h" 
#include "xppcon.h" 

#define xbeK_KeyMask            0x0000FFFF // extract pure key code 
#define xbeK_Virtual            0x00010000 // flag for special keys 
#define xbeK_Shift              0x00020000 
#define xbeK_Alt                0x00040000 
#define xbeK_Ctrl               0x00080000 

#define xbeB_Event              0x00100000 
#define xbeB_PartEvent          0x00200000 
#define xbeP_User               0x08000000 

/* 
splitEvent( nEvent, [@isShift], [@isCntrl], [@isAlt], 
            [@isVirtual], [@isSpecialEvent] ) -> nKeyCode 

 Note: to use isupper(), iscntrl() and tolower() the 
 C-Library has to be initialised first! 
*/ 
XPPRET XPPENTRY splitEvent( XppParamList paramList ) 
{ 
ULONG           event; 
ULONG           key; 
ContainerHandle chFlag; 
BOOL            isRef; 

/* 
   read parameter with event code 
*/ 
event = _parnl( paramList, 1 ); 
/* 
   get shift and control state of alphabetic characters 
*/ 
key = event & xbeK_KeyMask; 
if (! (event & (xbeK_Virtual|xbeB_Event|xbeB_PartEvent|xbeP_User))) 
{ 
   if (isupper(key)) 
   { 
      key = tolower(key); 
      event |= xbeK_Shift; 
   } 
   if (iscntrl(key)) 
   { 
      key = 'a'-1 + key; 
      event |= xbeK_Ctrl; 
   } 
} 
/* SHIFT-Key ? */ 
chFlag = _conParam( paramList, 2, &isRef ); 
if (! isRef) 
{ 
   _conRelease( chFlag ); 
} 
else 
{ 
   _conPutL( chFlag, event & xbeK_Shift ); 
} 
/* CONTROL-Key ? */ 
chFlag = _conParam( paramList, 3, &isRef ); 
if (! isRef) 
{ 
   _conRelease( chFlag ); 
} 
else 
{ 
   _conPutL( chFlag, event & xbeK_Ctrl ); 
} 
/* ALTERNATE-Key ? */ 
chFlag = _conParam( paramList, 4, &isRef ); 
if (! isRef) 
{ 
   _conRelease( chFlag ); 
} 
else 
{ 
   _conPutL( chFlag, event & xbeK_Alt ); 
} 
/* Special-Key ? (Function-Keys, Cursor-Keys, ...) */ 
chFlag = _conParam( paramList, 5, &isRef ); 
if (! isRef) 
{ 
   _conRelease( chFlag ); 
} 
else 
{ 
   _conPutL( chFlag, event & xbeK_Virtual ); 
} 
/* Special Event ? (Mouse events, Xbase-Part events, ... ) */ 
chFlag = _conParam( paramList, 6, &isRef ); 
if (! isRef) 
{ 
   _conRelease( chFlag ); 
} 
else 
{ 
   _conPutL( chFlag, event & (xbeB_Event|xbeB_PartEvent|xbeP_User) ); 
} 

_retnl( paramList, key); 
}

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Function _conParam() Foundation