# StructInsert

Inserts the specified key-value pair into the specified structure. Returns Yes if the insert was successful and No if an error occurs.

See also StructClear, StructDelete, StructFind, StructIsEmpty, StructKeyArray, StructCount, StructKeyArray, and StructUpdate.

### Syntax

    StructInsert(structure, key, value [, allowoverwrite ])

##### structure

Structure to contain the new key-value pair.

##### key

Key that contains the inserted value.

##### value

Value to be added.

##### allowoverwrite

Optionally indicates whether to allow overwriting an existing key. The default is FALSE.

### Usage

This function throws an exception if structure does not exist or if key exists and allowoverwrite is set to FALSE.

### Example

    <!--- This example shows how to use the StructInsert
          function. It calls the CF_ADDEMPLOYEE custom tag,
          which uses the addemployee.cfm file. --->
    <HTML>
    <HEAD>
    <TITLE>Add New Employees</TITLE>
    </HEAD>

    <BODY>
    <H1>Add New Employees</H1>
    <!--- Establish parms for first time through  --->
    <CFPARAM NAME="FORM.firstname" DEFAULT="">
    <CFPARAM NAME="FORM.lastname" DEFAULT="">
    <CFPARAM NAME="FORM.email" DEFAULT="">
    <CFPARAM NAME="FORM.phone" DEFAULT="">
    <CFPARAM NAME="FORM.department" DEFAULT="">

    <CFIF FORM.firstname EQ "">
     <P>Please fill out the form.
    <CFELSE>
      <CFOUTPUT>
       <CFScript>
         employee=StructNew();
         StructInsert(employee, "firstname", FORM.firstname);
         StructInsert(employee, "lastname", FORM.lastname);
         StructInsert(employee, "email", FORM.email);
         StructInsert(employee, "phone", FORM.phone);
         StructInsert(employee, "department", FORM.department);
      </CFScript>

      <P>First name is #StructFind(employee, "firstname")#</P>
      <P>Last name is #StructFind(employee, "lastname")#</P>
      <P>EMail is #StructFind(employee, "email")#</P>
      <P>Phone is #StructFind(employee, "phone")#</P>
      <P>Department is #StructFind(employee, "department")#</P>
      </CFOUTPUT>

      <!--- Call the custom tag that adds employees --->
      <CF_ADDEMPLOYEE EMPINFO="#employee#">
    </CFIF>

    <Hr>
    <FORM ACTION="structinsert.cfm" METHOD="post">
    <P>First Name:&nbsp;
    <INPUT NAME="firstname" TYPE="text" hspace="30" maxlength="30">
    <P>Last Name:&nbsp;
    <INPUT NAME="lastname" TYPE="text" hspace="30" maxlength="30">
    <P>EMail:&nbsp;
    <INPUT NAME="email" TYPE="text" hspace="30" maxlength="30">
    <P>Phone:&nbsp;
    <INPUT NAME="phone" TYPE="text" hspace="20" maxlength="20">
    <P>Department:&nbsp;
    <INPUT NAME="department" TYPE="text" hspace="30" maxlength="30">

    <P>
    <INPUT TYPE="submit" VALUE="OK">
    </FORM>

    </BODY>
    </HTML>