gc_util_insert_parm_ref( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_util_insert_parm_ref(parm_blkpp, setID, parmID, data_size, datap)
Inputs:	GC_PARM_BLKP **parm_blkpp	pointer to the address of a valid GC_PARM_BLK
	unsigned short setID	set ID of parameter to be inserted
	unsigned short parmID	parm ID of parameter to be inserted
	unsigned char data_size	size of the data in bytes
	void *datap	pointer to the parameter data
Returns:	0 if successful <0 if failure
Includes:	gclib.h gcerr.h
Category:	GC_PARM_BLK utility
Mode:	synchronous
Platform and Technology:	All

Description

The gc_util_insert_parm_ref( ) function must be used to insert a parameter by reference into a GC_PARM_BLK. A new GC_PARM_BLK can be created by inserting the first parameter into the block and setting *parm_blkpp to NULL. A parameter can be inserted in an existing GC_PARM_BLK by setting *parm_blkpp to the address of that block.

Note: When the parameters in the GC_PARM_BLK are retrieved via the gc_util_next_parm( ) function, they are retrieved in the same order in which they were inserted.

Parameter	Description
parm_blkpp	points to the address of a valid GC_PARM_BLK where the parameter is to be inserted. Set *parm_blkpp to NULL if the parameter is to be inserted into a new block.
setID	set ID of the parameter to be inserted
parmID	parm ID of the parameter to be inserted
data_size	size, in bytes, of the data associated with this parameter
datap	points to the data associated with this parameter

Termination Events

None

Cautions

• The gc_util_insert_parm_ref( ) function does not check whether the set ID or the parm ID is valid, nor does it check for duplicate parameters.
• To avoid a memory leak, any GC_PARM_BLK created must be deleted using the gc_util_delete_parm_blk( ) function.
• The maximum size of a GC_PARM_BLK is defined as PARM_BLK_HUGE bytes. If the maximum size is reached when inserting a parameter, the function will return an EGC_NOMEM error.

Errors

If this function returns <0 to indicate failure, use the gc_ErrorInfo( ) function to retrieve the reason for the error. See the "Error Handling" section in the Global Call API Programming Guide. All Global Call error codes are defined in the gcerr.h file.

Example

#include "gclib.h" 
void main( ) 
{
    GC_PARM_BLKP my_blkp = NULL;
    GC_PARM_DATAP my_parmp;
    int type = 1; 
    /* insert parm by reference */
    if ( gc_util_insert_parm_ref( &my_blkp, GC_SET_SERVREQ, PARM_REQTYPE,
         sizeof( int ), &type ) != GC_SUCCESS )
    {
        /* Process error */
    } 
    /* insert parm by value */
    if ( gc_util_insert_parm_val( &my_blkp, GC_SET_SERVREQ, PARM_ACK,
         sizeof( short ), GC_ACK ) != GC_SUCCESS )
    {
        /* Process error */
    } 
    /* Now we should have a GC_PARM_BLK with 2 parameters */ 
    /* Following use of gc_util_next_parm retrieves the first parameter in a
     * GC_PARM_BLK, which in this case is PARM_REQTYPE */
    my_parmp = gc_util_next_parm( my_blkp, NULL ); 
    /* Retrieve the next parameter after getting the first one */
    my_parmp = gc_util_next_parm( my_blkp, my_parmp ); 
    /* This function finds and returns specified parameter, NULL if not found */
    my_parmp = gc_util_find_parm( my_blkp, GC_SET_SERVREQ, PARM_ACK ); 
    /* After GC_PARM_BLK is no longer needed, delete the block */
    gc_util_delete_parm_blk( my_blkp ); 
    /* Set my_blkp to NULL now that the block has been deleted */
    my_blkp = NULL;
} 

See Also

• gc_util_insert_parm_val( )
• gc_util_delete_parm_blk( )

Click here to contact Telecom Support Resources