• <GetStart>
  • CSPro User's Guide
    • The CSPro System
    • Data Dictionary Module
    • The CSPro Language
    • Data Entry Module
    • Batch Editing Applications
    • Tabulation Applications
    • Data Sources
    • CSPro Statements and Functions
      • Statement Format Symbols
      • Alphabetical List of Functions and Statements
      • List of Reserved Words
      • Deprecated Features
      • Declaration Statements
      • Symbol Functions
      • Item Functions
      • Array Object
      • Audio Object
      • Barcode and QR Codes
      • Case Object
      • Document Object
      • File Object
      • Freq Object
      • Geometry Object
      • HashMap Object
      • Image Object
      • List Object
      • Map Object
      • Path
      • Pff Object
      • SystemApp Object
      • ValueSet Object
      • Program Control Statements
      • Assignment Statements
      • Data Entry Statements and Functions
      • Batch Edit Statements
      • Numeric Functions
      • String Functions
      • Multiple Occurrence Functions
        • Average Function
        • Count Function
        • CurOcc Function
        • Delete Function
        • GetOccLabel Function
        • Insert Function
        • Max Function
        • MaxOcc Function
        • Min Function
        • NOccurs Function
        • Seek Function
        • SeekMax Function
        • SeekMin Function
        • SetOccLabel Function
        • SOccurs Function
        • Sort Function
        • Sum Function
        • Swap Function
        • TotOcc Function
      • General Functions
      • Date and Time Functions
      • External File Functions
      • Synchronization Functions
    • Templated Reporting System
    • HTML and JavaScript Integration
    • Action Invoker
    • Appendix
  • <CSEntry>
  • <CSBatch>
  • <CSTab>
  • <DataViewer>
  • <TextView>
  • <TblView>
  • <CSFreq>
  • <CSDeploy>
  • <CSPack>
  • <CSDiff>
  • <CSConcat>
  • <Excel2CSPro>
  • <CSExport>
  • <CSIndex>
  • <CSReFmt>
  • <CSSort>
  • <ParadataConcat>
  • <ParadataViewer>
  • <CSCode>
  • <CSDocument>
  • <CSView>
  • <CSWeb>

Insert Function

Format
b = insert(group_nameʃ(occurrence)ʅ);

b = insert(group_name, first_occurrence)ʃ, last_occurrenceʅ);
Description
The insert function inserts missing or otherwise needed data records or item occurrences in the current case. It is primarily intended for use in batch applications. It should be used with extreme caution in data entry applications because of possible conflicts between the operator's actions and the program logic.
The first syntax inserts a single occurrence of the record. When inserting a singly-occurring record, it is not necessary to specify the occurrence. The second syntax inserts one or more occurrences of a record, starting with the first_occurrence and inserting up to the last_occurrence. This allows for the mass inserts of record occurrences.
Return Value
The function returns a logical value of 1 (true) if successful and 0 (false) otherwise.
Example 1 (Multiply-Occurring Records)
In the following example there is a data item in the housing record called H13_PERSONS, which contains the total number of people living in the household. We have decided that if the number of population records found in the household is less than this variable, we will insert the missing number of population record(s).
do numeric i = count(PERSON_REC) + 1 while i <= H13_PERSONS
  insert(PERSON_REC(i));
enddo;
It makes no difference if the population record has been defined in the dictionary as required or not. What is important is that it was defined as a multiply-occurring record.
Example 2 (Singly-Occurring Records)
For this example, we are processing data that did not require housing records to be present. However, now we want to force the existence of housing records. We could implement this as follows:
if totocc(HOUSING_REC) = 0 then
    insert(HOUSING_REC); // note the absence of a subscript
endif;
To accomplish this, the housing record must be set to "Required=No" in the dictionary. You cannot use this function for a singly-occurring record when the record is required.
See also: Delete Function