Custom Program Wizard
Menu Path: System Administration 
Tools Customization Custom Program Wizard
Purpose
Create new windows for custom programs.
Overview
Use Custom Program Wizard to create custom windows if you have created customer extracts or reports in Progress, and you want to build a user interface for these programs.
Note To use Custom Program Wizard, you must have an Apprise® Design Studio license.
Before you can use Custom Program Wizard to create a custom window, you must create a .p for the custom program. Additionally, if the custom program will output data to a Crystal Reports form, you must create the .rpt file, and set up a custom report record in Custom Report Maintenance.
If you are creating a custom program that uses Crystal Reports, the Crystal Reports .rpt file and the custom program .p file should have the same file name (e.g., cpwcrystal.p and cpwcrystal.rpt).
NOTE Store custom programs in a separate folder in the Apprise folder structure called <Company Name>_Custom (e.g., CompanyXYZ_Custom). After creating this folder, the folder must be added to the PROPATH of the AppServer. If you need guidance on updating the PROPATH of the AppServer, contact the Apprise Professional Services Team.
You can use Apprise APIs in custom programs. For information on Apprise APIs, refer to the Apprise API User's Guide.
You can also import custom window definitions in Custom Program Wizard Import.
Creating a Custom Window
To create a custom window:
-
If you are creating a custom program that will output data using a Crystal Reports form, select the Crystal radio button. Otherwise, leave the Non-Crystal radio button selected.
-
If you selected the Crystal radio button in step 1, enter the custom report name (set up in Custom Report Maintenance) in the Report Name field. Otherwise, enter the custom program file name (with the .p file extension) in the File Name field and an output file extension in the Output Extension field.
-
Select a default output method for the custom program. Users can change the output method when running the custom program.
-
Enter any notes or instructions that you want users to see when running the custom program in the Notes field.
-
Click the Input Parameters tab.
-
Specify the input parameters for the custom program. For each input parameter, a field will display in the window associated with the custom program. The custom program .p file should define each input parameter used to filter data for the custom program.
-
Enter the field label users will see for the input parameter in the Name field.
-
Enter the input parameter order number (1 for the first parameter, 2 for the second parameter, etc.) in the Parameter Order field. Enter 0 if you want to create a field associated with another previously created input parameter, such as a customer name associated with a customer code input parameter.
-
Click the Lookup button for the Data Type field, and select the type of data for the input parameter.
-
If you selected Character in substep c, enter the number of characters the user can enter for the input parameter in the Length field. If you selected Numeric in substep c, enter the number of integer and decimal places the user can enter for the input parameter in the Integer Places and Decimal Places fields, and then select whether to display thousands separators.
-
If you want a default value to be entered for the input parameter, enter the value in the Default Value field.
-
If you want users to be able to select values for the input parameter, select the Use Drop Browser check box. If you select this check box, you can use one of the following methods for setting the values from which the user can select:
-
Enter a Progress query in the Syntax field. If you want to allow users to select multiple values for the input parameter, select the Allow Multiple Choices check box.
-
Select the Valid Values List check box, and enter a list of values in the List Values field. Each value must be separated by a caret (^) character. If you want to allow users to select multiple values for the input parameter, select the Allow Multiple Choices check box.
-
Select the Use Standard Browser check box, and enter a standard Lookup window name in the Standard Browser field.
-
-
If you did not select the Use Standard Browser check box in substep f, enter the related database table and field for the parameter in the Related Table and Related Field fields.
-
If you entered 0 in substep b, enter the input parameter related to the input parameter in the Related Parameter field.
-
If the parameter is related to a logical parameter, enter the logical parameter in the Related Toggle field. You can also select the Enable When Checked check box if the field for the parameter will be enabled when the check box for the related logical parameter is selected.
-
If you want to validate data entered for the input parameter, select the Validate check box.
-
If you want to make the field for the input parameter a required field, select the Required check box.
-
If you want to disable the field for the input parameter, select the Disabled check box.
-
Click the Add button.
-
Repeat substeps a to m for all input parameters.
-
-
Click the Finalize tab.
-
If your company has set up submenus for the Custom module, click the Lookup button for the Menu Name field, and select the submenu on which to add the menu item for the custom program.
-
Enter text to appear as the menu for the custom program in the Menu Description field.
-
Enter text to appear in the title bar of the window for the custom program in the Screen Title field.
-
Select the label to display for the ribbon button in the custom window in the Print Button Label radio set.
-
If you do not want to allow all users to access the custom program, clear the Allow Default Access check box.
-
Click the OK button in the ribbon.
To delete or edit a custom window created in Custom Program Wizard, use Custom Program Maintenance.
Sample Programs
The following sample programs illustrate how to properly create a custom program with or without using Crystal Reports forms.
Crystal Reports
The following is a sample program, which illustrates how to create a custom program for a Crystal Reports form:
{cust-rpt.i} /*This .i has some necessary procedures for the custom report*/
/*Report tables definition*/
DEFINE TEMP-TABLE report-data NO-UNDO
FIELD prod-cat AS CHAR
INDEX idx-main IS PRIMARY prod-cat.
DEFINE TEMP-TABLE report-trl NO-UNDO
FIELD prod-code AS CHAR
FIELD prod-name AS CHAR
FIELD prod-cat AS CHAR
INDEX idx-main IS PRIMARY prod-code.
PROCEDURE run-report:
{cust-rpt-input.i} /*This .i includes input parameters passed in by the system, and also it will do some initialization*/
/*Tell the system which report tables are used in the report.
In this example it uses two tables. You can add more tables
by separating them with "," */
RUN set-report-buffers("report-data,report-trl").
/*Retrieve data from the database*/
FOR EACH category WHERE
category.system-id = "Apprise"
NO-LOCK:
CREATE report-data.
ASSIGN report-data.prod-cat = category.category-code.
RELEASE report-data.
FOR EACH product WHERE
product.system-id = "Apprise"
NO-LOCK:
CREATE report-trl.
ASSIGN report-trl.prod-code = product.product-code
report-trl.prod-name = product.product-name
report-trl.prod-cat = category.category-code.
RELEASE report-trl.
END.
END.
OPEN_CUSTOM_REPORT(). /*Open the report*/
END.
Without Crystal Reports
The following is a sample program, which illustrates how to create a custom program that does not use a Crystal Reports form:
/* A DEFINE INPUT PARAMETER statement is needed for each parameter defined for this program.
The sequence and data types must match those defined for the program
on the Input Parameters tab of the Custom Program Wizard window. */
DEFINE INPUT PARAMETER ip-from-cust AS CHARACTER NO-UNDO.
DEFINE INPUT PARAMETER ip-to-cust AS CHARACTER NO-UNDO.
/* {RPT-INPUT.I} is required and must be on its own exactly as it appears below.
It must directly follow the DEFINE INPUT PARAMETER statements. */
{RPT-INPUT.I}
/* Functions related to the "Excel" output option
IsExcel - Returns YES if printing to Excel, NO otherwise.
Usage - IF IsExcel() THEN
SetExcelNumHeaderRows - Sets the number of rows in the column header. Accepts integer values of 1 or greater.
Usage - SetExcelNumHeaderRows(2).
SetExcelColumnFormat - Sets the Excel header all at once. Accepts a non-blank CHARACTER type, validates for each entry
delimited by ^ to be a non-zero non-negative integer.
1 - General
2 - Text
Usage - SetExcelColumnFormat("1^1^2"). Will format column A and B as general, column C as text.
AddExcelColumnFormat - Add 1 column to the Excel header. Accepts a non-blank string, validates for each entry
delimited by ^ to be a non-zero non-negative integer.
1 - General
2 - Text
Usage - AddExcelColumnFormat("2"). The NEXT column in the Excel format will be formatted as Text */
FOR EACH custname WHERE
custname.SYSTEM-ID = curr-sys-id AND
custname.cust-code >= ip-from-cust AND
custname.cust-code <= ip-to-cust
NO-LOCK:
DISPLAY custname.cust-code custname.order-class custname.order-priority.
END.
Using cpwcommon.i
cpwcommon.i is a file that can be used in Custom Program Wizard programs. It is used to manage system IDs in Custom Program Wizard, and for common functions, such as unit of measure conversions, and international date format setup.
The following are functions that can be used:
FUNCTION check-user-security RETURNS LOGICAL (INPUT ip-check-type AS CHARACTER,
INPUT ip-check-key AS CHARACTER,
INPUT ip-user-id AS CHARACTER) IN SUPER.
/* Convert qty from one unit of measure to another. */
FUNCTION icumconvf RETURNS DECIMAL (INPUT ip-um-key-from AS CHARACTER,
INPUT ip-um-key-to AS CHARACTER,
INPUT ip-inv-units AS LOGICAL,
INPUT ip-from-qty AS DECIMAL,
INPUT ip-dens-w-um-key AS CHARACTER,
INPUT ip-dens-v-um-key AS CHARACTER,
INPUT ip-density AS DECIMAL) IN SUPER.
FUNCTION umconv RETURNS DECIMAL (INPUT ip-um-key-from AS CHARACTER, /* um.um-key */
INPUT ip-um-key-to AS CHARACTER, /* um.um-key */
INPUT ip-from-qty AS DECIMAL) IN SUPER.
FUNCTION umconv-r RETURNS DECIMAL(INPUT ip-um-key-from AS CHAR,
INPUT ip-um-key-to AS CHAR,
INPUT ip-from-qty AS DECIMAL,
OUTPUT op-rc AS INT) IN SUPER.
/* Returns the current system id. */
FUNCTION get-sysid RETURNS CHARACTER (INPUT ip-reserved AS CHARACTER) IN SUPER.
ASSIGN curr-sys-id = get-sysid("").
/* TEXT BASED reports only Date Functions*/
FUNCTION FORMATTED_OUTPUT_DATE RETURNS CHARACTER (in-date AS DATE,
in-format AS CHARACTER,
in-seperator AS CHARACTER,
in-year-display AS INTEGER) IN SUPER.
FUNCTION SET_OUTPUT_DATE_FORMAT RETURNS LOGICAL (in-format AS CHARACTER,
in-seperator AS CHARACTER) IN SUPER.
FUNCTION OUTPUT_DATE RETURNS CHARACTER (in-date AS DATE) IN SUPER.
FUNCTION SHORT_OUTPUT_DATE RETURNS CHARACTER (in-date AS DATE) IN SUPER.
Example 1 of using cpwcommon.i:
DEFINE INPUT PARAMETER ip-customer-code AS CHARACTER NO-UNDO.
/* {RPT-INPUT.I} is required and must be on its own exactly as it appears below.
It must directly follow the DEFINE INPUT PARAMETER statements. */
{RPT-INPUT.I}
/* Apprise populates the io-excel variable with "Excel"
when the 'Output to Excel' option is selected;
io-excel is blank for all other output options */
FOR EACH custname WHERE
custname.system-id = curr-sys-id AND
custname.cust-code = ip-customer-code
NO-LOCK:
/* check if user has permission for the customer */
IF check-user-security(INPUT "Customer", INPUT custname.cust-key, INPUT USERID({&Apprise})) THEN
DO:
DISPLAY custname.cust-code custname.order-class custname.order-priority.
END.
ELSE
DO:
DISPLAY "The user has no permission for this customer.".
END.
END.
Example 2 of using cpwcommon.i:
{inv-err.i} /* This is the global-defines that contain the error codes */
DEFINE INPUT PARAMETER ip-product-code AS CHARACTER NO-UNDO.
DEFINE INPUT PARAMETER ip-um-code AS CHARACTER NO-UNDO.
DEFINE VARIABLE qty-ordered-01 AS INTEGER INIT 0 NO-UNDO.
DEFINE VARIABLE qty-ordered-02 AS INTEGER INIT 0 NO-UNDO.
DEFINE VARIABLE qty-ordered-03 AS INTEGER INIT 0 NO-UNDO.
DEFINE VARIABLE op-rc AS INTEGER NO-UNDO.
/* {RPT-INPUT.I} is required and must be on its own exactly as it appears below.
It must directly follow the DEFINE INPUT PARAMETER statements. */
{RPT-INPUT.I}
/* Apprise populates the io-excel variable with "Excel"
when the 'Output to Excel' option is selected;
io-excel is blank for all other output options */
RUN summ-product-quantity.
PROCEDURE summ-product-quantity:
IF NOT CAN-FIND(FIRST product WHERE
product.system-id = curr-sys-id AND
product.product-code = ip-product-code) THEN
DO:
MESSAGE "Invalid product code.".
RETURN.
END.
FOR FIRST product WHERE
product.system-id = curr-sys-id AND
product.product-code = ip-product-code
NO-LOCK,
EACH oe-trailer WHERE
oe-trailer.system-id = curr-sys-id AND
oe-trailer.product-key = product.product-key
NO-LOCK:
FIND FIRST um WHERE
um.um-code = ip-um-code
NO-LOCK NO-ERROR.
IF AVAILABLE um THEN
DO:
IF (oe-trailer.um-key <> um.um-key) THEN
DO:
/* icumconvf returns the converted quantity and sets density parameters */
ASSIGN qty-ordered-01 = qty-ordered-01 + icumconvf(INPUT oe-trailer.um-key,
INPUT um.um-key,
INPUT NO,
INPUT oe-trailer.qty-ordered,
INPUT "", /* density weight UM key */
INPUT "", /* density volume UM key */
INPUT 0.0). /* density value parameter */
/* umconv returns the converted quantity */
ASSIGN qty-ordered-02 = qty-ordered-02 + umconv(INPUT oe-trailer.um-key,
INPUT um.um-key,
INPUT oe-trailer.qty-ordered).
/* umconv-r returns the converted quantity and error code*/
ASSIGN qty-ordered-03 = qty-ordered-03 + umconv-r(INPUT oe-trailer.um-key,
INPUT um.um-key,
INPUT oe-trailer.qty-ordered,
OUTPUT op-rc).
END.
ELSE
DO:
ASSIGN qty-ordered-01 = qty-ordered-01 + oe-trailer.qty-ordered.
ASSIGN qty-ordered-02 = qty-ordered-02 + oe-trailer.qty-ordered.
ASSIGN qty-ordered-03 = qty-ordered-03 + oe-trailer.qty-ordered.
END.
END.
ELSE
DO:
MESSAGE "Invalid UM code.".
RETURN.
END.
END.
CASE op-rc:
WHEN {&um-bad-from-unit} THEN /* 00010 */
MESSAGE "From UM is incorrect.".
WHEN {&um-bad-to-unit} THEN /* 00020 */
MESSAGE "To UM is incorrect.".
WHEN {&um-incompatible-units} THEN /* 00030 */
MESSAGE "Incompatible UMs.".
WHEN {&um-other-error} THEN /* 00040 */
MESSAGE "Other UM error.".
WHEN {&um-ok} THEN /* 00000 */
MESSAGE "UM is correct.".
WHEN {&dens-bad-weight-unit} THEN /* 00110 */
MESSAGE "Density weight unit is incorrect.".
WHEN {&dens-bad-volume-unit} THEN /* 00120 */
MESSAGE "Density volume unit is incorrect.".
WHEN {&dens-other-error} THEN /* 00130 */
MESSAGE "Other density error.".
WHEN {&dens-ok} THEN /* 00000 */
MESSAGE "Density is correct.".
END CASE.
IF op-rc = 0 THEN
DO:
DISPLAY qty-ordered-01.
DISPLAY qty-ordered-02.
DISPLAY qty-ordered-03.
END.
END PROCEDURE.
Example 3 of using cpwcommon.i:
DEFINE INPUT PARAMETER ip-order-num AS CHARACTER NO-UNDO.
/* {RPT-INPUT.I} is required and must be on its own exactly as it appears below.
It must directly follow the DEFINE INPUT PARAMETER statements. */
{RPT-INPUT.I}
/* Apprise populates the io-excel variable with "Excel"
when the 'Output to Excel' option is selected;
io-excel is blank for all other output options */
FOR EACH oe-header WHERE
oe-header.system-id = curr-sys-id AND
oe-header.order-num = ip-order-num
NO-LOCK:
/* print the order date in standard format */
MESSAGE oe-header.order-num OUTPUT_DATE(INPUT oe-header.order-date).
/* print the order date in our format */
MESSAGE oe-header.order-num FORMATTED_OUTPUT_DATE(INPUT oe-header.order-date,
INPUT "DMY",
INPUT "-",
INPUT 4).
/* set the date format */
IF NOT SET_OUTPUT_DATE_FORMAT(INPUT "DMY", INPUT "/") THEN
DO:
MESSAGE "Invalid date format.".
END.
/* print the order date in the short format */
MESSAGE oe-header.order-num SHORT_OUTPUT_DATE(INPUT oe-header.order-date).
END.
Ribbon Home Tab Buttons
|
Button |
Description |
|
Exit |
Click this button to close the Custom Program Wizard window. |
|
OK |
Click this button to finish creating the custom window. When you click this button, the menu cache is cleared for all users and the new custom program is added to the menus. |
|
PROPATH |
Click this button to display Custom Program Wizard Propath, which allows you to view the AppServer PROPATH, and determine which folder contains the custom program file entered in the File Name field. |
|
Compile |
Click this button to compile the custom program file entered in the File Name field. |
Procedure Information Tab Fields and Buttons
|
Field or Button |
Description |
|
If the custom program does not use Crystal Reports, enter the file name for the custom program, including the .p file extension. If the custom program uses Crystal Reports, enter the custom report name (as set up in Custom Report Maintenance). |
|
|
Select whether the custom program is for a Crystal Reports form or other program. |
|
|
Enter a file extension for output text reports. This field is only available if the Non-Crystal radio button is selected. |
|
|
Select a default method for outputting data for the custom program. This is selected by default on the Report Options tab of the window associated with the custom program. |
|
|
Enter basic instructions on how to use the custom program. The notes you enter in this field appear at the bottom of the custom window generated for the custom program. You can use this field to store instructions for the custom program that users will see when using it. |
Input Parameters Tab Fields and Buttons
|
Field or Button |
Description |
|
Enter a label you want to display for the input parameter field in the window associated with the custom program. |
|
|
Enter the input parameter order number (1, 2, 3, etc.). Enter 0 only for a field you want to display that is not an input parameter. You can enter 0 to create a field associated with another input parameter, such as a customer name associated with a customer code input parameter. If you enter a value greater than 0 in this field, it must be unique for the custom program. Example Your custom program uses one input parameter for a customer code. You enter 1 for the parameter order for this input parameter. You also want to display the customer name associated with the customer code. Enter 0 for it. |
|
|
Click the Lookup button to select a data type for the input parameter field. You can select one of the following:
|
|
|
Enter the maximum number of characters that can be entered in the field. This field is only available if you select Character in the Data Type field. This field defaults to the length of the database field entered in the Related Field field. |
|
|
Enter the number of integer places for the field. This field is only available if you select Numeric in the Data Type field. This field defaults to the number of integer places of the database field entered in the Related Field field. |
|
|
Enter the number of decimal places for the field. This field is only available if you select Numeric in the Data Type field. This field defaults to the number of decimal places of the database field entered in the Related Field field. |
|
|
Select this check box to include thousand separators in the numeric values in the field. This check box is selected by default. This check box is only available if you select Numeric in the Data Type field. |
|
|
Enter a default value for the field. If you selected Logical in the Data Type field, select this check box to select the check box for the field by default. |
|
|
Select this check box to include a Lookup button to the right of the field that allows the user to select a value for the field from a Lookup window. This check box is only available if you select Character or Numeric in the Data Type field. |
|
|
Select this check box to use a standard Lookup window for the field. This check box is only enabled if the Allow Multiple Choices check box is cleared. |
|
|
Select this check box to require the user to enter a value from a list you enter in the List Values field. This check box is only enabled if you select the Use Drop Browser check box and clear the Use Standard Browser check box. |
|
|
Select this check box if the field will store a file name, and you want to allow users to be able to select a file from a separate dialog box. This check box is only enabled if Character is selected in the Data Type field. |
|
|
Select this check box if the field will store a folder path, and you want to allow users to be able to select a folder from a separate dialog box. This check box is only enabled if Character is selected in the Data Type field. |
|
|
Select this check box to allow the user to select multiple choices. If you select this check box, you must define a list or query for the values from which the user can select. The user will be able to add values to and from a grid of selected values. They can also use the Shift and Ctrl keys to select multiple values. This check box is only enabled if you select Character or Numeric in the Data Type field and select the Use Drop Browser check box. |
|
|
Select this check box to reset the field to the default value after printing a report. |
|
|
Select this check box to allow the user to enter an abbreviated number for order, invoice, or bill of lading numbers. EXAMPLE If sales order number NJ000000001 exists and this check box is selected for an order number field, users can type NJ.1 in the field. If this check box is selected for a field with a length of 13 or greater, the field will behave like the order, purchase order, work order, and invoice number fields in Apprise. If this check box is selected for a field with a length of 17 or greater that has a related table of bol-hdr, it will behave like the bill of lading number fields in Apprise. This check box is only enabled if Character is selected in the Data Type field. |
|
|
Enter the syntax for the Lookup window. This field is only enabled if you select the Use Drop Browser check box, and only available if you clear the Valid Values List and Use Standard Browser check boxes. |
|
|
List Values |
Enter a list of valid values that the user can select for the field. Separate each value in the list with a caret (^) character. This field is only available if you select the Valid Values List check box. |
|
Enter the name of a standard Lookup window, or click the Lookup button to select a standard Lookup window. This field is only available if you select the Use Standard Browser check box. Note To determine the name of a Lookup window, navigate to it in Apprise, and select Help |
|
|
Enter a database table related to the field, or click the Lookup button to select a related table. This field is disabled and the value automatically entered if you enter a standard Lookup window in the Standard Browser field. |
|
|
Enter a database field related to the field, or click the Lookup button to select a related field. This field is disabled and the value automatically entered if you enter a standard Lookup window in the Standard Browser field. |
|
|
Enter a parameter related to the field, or click the Lookup button to select a related parameter. This field is only enabled if the Allow Multiple Choices check box is cleared. |
|
|
Enter a related logical parameter, or click the Lookup button to select a related logical parameter. This field is only enabled if the Disabled check box is cleared. Example If you created an All Customers parameter, you would enter it in this field for a Customer Code parameter. |
|
|
Select this check box to enable the field for the parameter only when the check box for the related logical parameter is selected. This check box is only enabled if a related logical parameter is entered in the Related Toggle field. |
|
|
Select this check box to verify that values entered or selected for the input parameter field exist in the related database field. This check box is only enabled if you enter a related table and field. |
|
|
Select this check box to make the field a required field. Required fields appear in red font. |
|
|
Select this check box to disable the field. |
|
|
Click this button to add a field to the Fields grid. |
|
|
Click this button to remove the selected field from the Fields grid. |
|
|
This grid displays all the fields for the custom window. You can move a field up or down in the window using the arrow buttons at the right of the grid. |
Finalize Fields Tab Fields and Buttons
|
Field or Button |
Description |
|
This field displays Custom to indicate that the custom window will be added to the Custom module. |
|
|
Click the Lookup button to select a submenu on which to add the custom window. Note Only use this field if your company has set up submenus for the Custom menu in AppriseCenter. |
|
|
Enter the text you want to appear as the menu for the custom program, or click the Lookup button to select a previously saved label. If a label was previously set up in Label Maintenance, you can enter the label code in the second field, or click the Lookup button for that field to select a label code. You can also click the button to the right of these fields to display Label Maintenance, which allows you to maintain labels displayed in Apprise. |
|
|
Enter the text you want to appear in the title bar of the window for the custom program, or click the Lookup button to select a previously saved label. If a label was previously set up in Label Maintenance, you can enter the label code in the second field, or click the Lookup button for that field to select a label code. You can also click the button to the right of these fields to display Label Maintenance, which allows you to maintain labels displayed in Apprise. |
|
|
Select the label to display in the ribbon for the custom window. The Print radio button is selected by default. EXAMPLE If the custom window is for a report that users will print, you would leave the Print radio button selected. |
|
|
Select this check box to allow all users to access the custom program from the menu. This check box is selected by default. |