BulkInsertField function

Syntax

BulkInsertField(ProjectName, Field.FieldName, ModelName, ClonePCode [, ExclProj])

Description

Use the BulkInsertField function to insert a source field into records and pages in a project if and only if the model field specified by ModelName exists on those records and pages.

If you specify a project that contains objects such as fields which have an upgrade action of delete, those objects are ignored.

Note:

You must have the role PeopleSoft Administrator assigned to your UserId in order to use this function.

Parameters

Parameter Description

ProjectName

The name of a project that is the source of records and pages to use.

Note: When passing the project name as a parameter, if the project contains definitions with an upgrade action of delete, the system ignores those definitions.

FieldName

The name of the field to be inserted. This name must be prefixed with the reserved word Field.

ModelName

The name of a field on which to model the inserted field. Attributes are cloned from it for records and pages, PeopleCode is modified, and SQL inserted.

ClonePCode

Specify whether to clone the PeopleCode from the model to this field. This parameter takes a Boolean value: True, clone the PeopleCode programs, False, do not.

ExclProj

The name of a project that has pages that should be ignored by this function.

Returns

A constant value. The values are:

Value Description

%MDA_Success

Bulk operation completed successfully.

%MDA_Failure

Bulk operation did not complete successfully.

Example

&pjm = "MYPROJ"; 
&ret =  BulkInsertField(&pjm, Field.OrgId, Field.DeptId, True, "EXCLPROJ");  
If (&ret = %MDA_Success) Then 
   MessageBox(0, "Metadata Fn Status", 0, 0, "BulkInsertField succeeded"); 
Else 
   MessageBox(0, "Metadata Fn Status", 0, 0, "BulkInsertField failed"); 
End-If;

Using the Log File

Information about this operation is stored in a log field. The directory where the log file is placed depends on where the function is run from:

  • If the function is run in two-tier, the log file is located at PS_HOME/BulkOps.txt. This is also the default location if the system cannot find the other paths.

  • If the function is run from an application server, the log file is located here:

    PS_CFG_HOME /APPSERV/Domain_Name/LOGS/BulkOps.txt

  • If the function is run from an Application Engine program, the log file is written to the process' output log directory, that is:

    PS_CFG_HOME /APPSERV/prcs/Domain_Name/log_output/Process_Name_Instance/BulkOps.txt

Considerations Inserting Fields into Records

In records, the source field is assigned the same record field properties as the model field on each record, and is inserted directly after the model field.

If the model field has a prompt table, a prompt table is created for the source field using the name of the source field with TBL appended to it.

If the record is either a SQL View or Dynamic View type, the associated SQL is modified by having the SELECT clause expanded to include the new field.

If the record is a subrecord, the parent records of type SQL View or Dynamic View that contain this subrecord are updated.

If the SQL contains the model field in the WHERE clause, or the SQL is complex, the associated record is inserted into a project called BLK_FieldName. You should examine this record and make any necessary changes.

If the model field has PeopleCode associated with it on the record or in a component, and ClonePCode has been set to True, this PeopleCode is cloned to the new field, with all references to the model field changed to refer to the new field.

Note:

Because using this function changes records that are used to build application tables, you must rebuild (alter) the specified project before these changes can be used.

Considerations Inserting Fields into Pages

If the model field is in a grid, the system inserts the new field into the grid next to the model field and assigns it the same page field properties.

If the model field is not in a grid, the system inserts the new field onto the page to the right of the model field (in the first open space) and assigns it the same page field properties. If the system detects a questionable field position, it inserts the page into a project called BLK_FieldName. The page will work as-is, however, the GUI layout may not be optimal, so you should examine these pages by hand.

The page field name property isn't cloned if it exists on the model field. Instead, the field name of the new field is used, since the page field name should be a unique identifier for page elements.

Note:

If the project you specified only contained pages and not records, you do not need to rebuild the project after using this function. The changes take affect when the component containing the page is reloaded.

Considerations Using this Function

This function is intended for use during configuration time only, before active runtime usage is initiated. Using this function during active runtime is not supported. Changes to data definitions are not recognized on currently loaded component. In general, changes aren't recognized until the component is reloaded.

Bulk operations are time consuming, therefore, referencing the log file to see the progress of an operation is recommended. These operations accommodate errors and continue processing, logging the overall progress of the operation.

WARNING:

These operations take place in a separate transaction from the page's save status: the initiation of any of these operations immediately changes the definitions, even if the page is subsequently cancelled.

Considerations Using the Exclusion Project

If you specify ExclProj, the following items that are both in ProjectName and ExclProj are not changed, that is, the field specified is not inserted to these items:

  • pages

  • records

  • associated SQL with records of type View

  • any PeopleCode associated with those items.

Individual SQL or PeopleCode items are not ignored by themselves, only as associated with records or pages.

Related Topics