Chapter 5: Define Processing Logic

This chapter contains the following sections:

Concepts of Processing Logic
Predefined Program Functions
Custom Program Functions
Mapping Screens to Database Fields
Control Points

Concepts of Processing Logic

Define processing logic

You complete your application by defining its processing logic using Online Express, a menu-driven painter that offers a fill-in-the-blanks approach. Online Express references the information that you have specified in the other APS painters and importers, and prompts you to define the processing logic for those specifications. You do the following to complete your application in Online Express:

Eight tasks you can perform with Online Express

Select predefined program functions. Online Express provides predefined program function logic, including teleprocessing and database read and write functions. You simply select the program function codes that you want.
Define custom program functions. You can define your own program functions to supplement the predefined functions. End users can execute custom functions just as they execute any predefined function.
Specify methods for executing functions. You specify the method by which the end user executes the functions. For example, the end user can either enter a code in a function field or press a key.
Map screen fields to database fields. Online Express automatically displays all screen fields that you have defined in the APS Screen Painter, so that you can map them to the appropriate fields in your database.
Define database access. For each database function that you select, you define one or more database calls that specify which record or records to read, and which database actions to perform on them, such as obtain, modify, store, and erase. This task is described in Define Database Access.
Customize the predefined functions. You can modify and supplement the default processing logic of the predefined functions as follows:
- Add your own logic at predefined locations in your program, called control points. This task is described in both this chapter and in Define Database Access.
- Override the default error processing of database calls. This task is described in Define Database Access.
Define savekey storage. You define savekey storage area(s) to store record key values during program execution if your program must do any of the following:
- Update records with the U(pdate), A(dd), and D(elete) program functions.
- Obtain records sequentially with the N(ext) program function
- Display repeated record blocks that the end user can scroll with the F(orward) and B(ackward) functions.
- Re-read repeated record blocks so that the end user can update and delete them with the M(odify) and E(rase) functions
Define Commarea storage. You use a program Commarea to store any data that your program passes between programs with the X(CTL), M(SG-SW), or C(all) functions.

Predefined Program Functions

Online Express provides predefined teleprocessing and database function logic. You simply select the predefined function codes that you need.

Teleprocessing functions

Teleprocessing (TP) functions transfer screen data and program control from the current program to another screen or program. The predefined TP functions include the following:

TP Function	Description
S(end)	Transmits an input/output screen.
M(SG-SW)	Schedules a new program and optionally passes a screen record or other data record to it.
X(CTL)	Transfers control to another program.
C(all)	Calls a subroutine or performs a CICS LINK.
C(lear)	Moves spaces or low-values to all I/O fields.
E(xit)	Terminates the program.

Database functions

Database functions read from and write to your application's database. The predefined database functions include the following:

Read Function	Description
Q(uery)	Obtains one or more records and displays data on the screen.
B(ackward)	Pages backward through a repeated record block.
F(orward)	Pages forward through a repeated record block.
N(ext)	Retrieves the next sequential record and displays data; not applicable to SQL.
R(efresh)	Re-reads the database when the end user executes any database write function on one or more repeated record block rows, and re-displays the record block to reflect the database updates.

Write Function	Description
A(dd)	Stores records.
D(elete)	Erases records.
U(pdate)	Modifies records.

Write Function

Description

A(dd)

Stores records.

D(elete)

Erases records.

U(pdate)

Modifies records.

Screen design dictates how you use functions

The screen design dictates which functions act on which fields. When you painted your screen, you designed it to display data in one of the following three formats:

One occurrence of data at a time. For example, your screen might display the name, address, and other information about a particular customer, as shown in Screen Displaying One Occurrence of Data. To query the record in this example, the end user enters q(uery) in the Function field and a value in the record key field, Customer Number. The developer has assigned the S(end) function to the PF3 key so that the end user can press PF3 to display the Main Menu.

Figure 5-1: Screen Displaying One Occurrence of Data

On such a screen, any function that you define for the program acts on all fields. You can select any of the following functions:

A(dd)	D(elete)	N(ext)	S(end)
C(all)	E(xit)	Q(uery)	U(pdate)
C(lear)	M(SG-SW)	R(efresh)	X(CTL)

Multiple occurrences of data, displayed in a repeated record block. For example, your screen might display rows of information about many items in inventory, as shown in Screen Displaying Multiple Occurrences of Data. Because this sample program has just one function--query--a function field is not required. The end user starts the query by entering a part number in the record key field. The developer has assigned the F(orward) and B(ackward) functions to the PF8 and PF7 keys so that the end user can press these keys to scroll through the repeated record block.

Figure 5-2: Screen Displaying Multiple Occurrences of Data

On such a screen, any function that you define for the program acts on all fields. You can select the same functions that are available for single occurrences of data, plus the F(orward) and B(ackward) functions for scrolling through the repeated block.

Both single and multiple occurrences of data. For example, your screen might display information about a single customer order and a list of the parts ordered, as shown in Screen Displaying Single and Multiple Occurrences of Data.

Figure 5-3: Screen Displaying Single and Multiple Occurrences of Data

If your screen displays both single and multiple occurrences of data, you might have to define two function fields:

A primary function field for updating the single occurrence record
A row function field, if you must update the repeated record block rows

Use the primary and row function fields to act upon data as follows:

Primary Function Field Functions	Data Acted On
Database read functions:
B(ackward)	All repeated record block row data
F(orward)	All repeated record block row data
N(ext)	All data on the screen
Q(uery)	All data on the screen
R(efresh)	All data on the screen
Database write functions:
A(dd)	Only the single occurrence data
D(elete)	Only the single occurrence data
U(pdate)	Only the single occurrence data
Teleprocessing functions:
C(all)	All data on the screen
C(lear)	All data on the screen
E(xit)	All data on the screen
M(SG-SW)	All data on the screen
S(end)	All data on the screen
X(CTL)	All data on the screen
A(dd)	A row of the repeated record block
D(elete)	A row of the repeated record block
U(pdate)	A row of the repeated record block

Screen Displaying Single and Multiple Occurrences of Data illustrates a screen displaying both single and multiple occurrences of data--information about a single customer order and a list of the parts ordered. The end user starts the query by entering q(uery) in the primary function field and a value in the record key field, Order No. Data displays in all fields. To update, add to, and delete from:

The customer order information, the end user enters function codes in the primary function field, Enter Function
The parts records in the repeated block, the end user enters function codes in the row function field, Act.

The developer has assigned the F(orward) and B(ackward) functions to the PF8 and PF7 keys so that the end user can scroll through the repeated block.

Other processing for multiple occurrences of data

You might want to process multiple occurrences of data for purposes other than displaying it in an updateable repeated record block. For example, you might want to:

Query a single record that has multiple values, such as 12 monthly sub-totals, and insert logic at a control point to move the data to a non-updateable repeated record block.
Loop on multiple records and display the data in a non-updateable repeated record block.
Loop on a record and insert logic at a control point to calculate record totals, and display just the totals in one occurrence of data.

Specifying Predefined Program Functions

To specify predefined program functions, follow these steps:

Ensure that you have done the following:
- Listed the components of your application on the Application Painter screen.
- Painted your program screens using the APS Screen Painter.
- Generated your program subschema(s) using the APS Database Importers.
Display the Application Painter screen.
Access Online Express
To start defining program functions for your first program, display the Online Express menu by entering ox in the selection field next to the program name.

Figure 5-4: Online Express Menu
Display the Program Definition screen by selecting Actions Program Definition, or entering option 1 in the Command field.

Figure 5-5: Program Definition Screen

Specify functions and function field(s)
Specify any of the following:

All database read and write functions that you want to include in your program
A primary function field, if you want the end user to execute the functions by entering codes in a function field
A row function field, if you want the end user to execute database write functions for repeated record block rows by entering function codes in a function field
The C(lear) and E(xit) teleprocessing functions; you define the other teleprocessing functions--S(end), X(CTL), M(SG-SW), and C(all)--in step 7
A field for displaying system messages
The initial cursor position

To specify the functions and fields above, complete the Program Definition screen fields as follows:

Field	Value
Function Field	The COBOL name of the primary function field where the end user enters function codes to execute program functions. This field is optional if you define just the q(uery) or a(dd) function. If you named this field FUNCTION or FUNCTION-name when you painted your screen, Online Express automatically displays the function field name.
Function Codes	Valid values: Database read functions: Q(uery) N(ext); not applicable for SQL F(orward) and B(ackward); applicable only for repeated record blocks R(efresh) Database write functions: U(pdate) A(dd) D(elete) Teleprocessing functions: C(lear). Moves spaces to all I/O fields. E(xit) Note: You can rename these default function codes with your own codes later in this procedure.

Row Function Field	The COBOL name of the function field where the end user enters database write functions that act only on repeated record block rows.
Row Function Codes	Valid values: U(pdate) A(dd) D(elete)
SYSMSG Field	The COBOL name of the system message field. If you named this field SYSMSG when you painted your screen, Online Express automatically displays this name.
Position Cursor on Field	By default Online Express positions the cursor on the function field for the non-repeated record block data. If you want to override this default with a different field, do one of the following: To use the initial cursor position field that you specified in the Screen Painter Field Attributes screen, blank out this field with spaces. Or, specify the override field in this field.

Press PF3 to return to the Online Express Menu.
Specify other teleprocessing functions
To specify the S(end), X(CTL), M(SG-SW), or C(all) teleprocessing functions, select Actions Alternate Functions, or enter option 2 in the Command field. The Alternate Functions screen displays, showing all function codes that you selected on the Program Definition screen, as illustrated in Program Definition Screen.

Figure 5-6: Alternate Functions Screen
Complete the screen fields as follows:
- Enter in the Function field any of the predefined teleprocessing function codes that you need--S(end), X(CTL), M(SG-SW), or C(all).
- Enter the objects of the functions - such as the screen to send or the program to transfer to -in the Reserved Function or Function Name field.
- Enter in the Program Input field the function code value that you want the end user to use to execute the function. The value can be 1-8 alphabetic characters.
  
  Notes:
  - To rename any default Program Input code with your own alternative alias code, see step 10.
  - You use the P(erform), G(lobal code), L(ocal code), and $ (invoke macro) codes to define custom functions. See Defining Custom Program Functions.
Specify how the end user executes the functions
Specify how you want the end user to execute the functions by choosing one of the following:
- Default. The end user enters a function code in your screen's function field(s). The codes are those that you specified on the Program Definition and Alternate Functions screens.
  - To rename the default codes with your own codes, perform step 10.
  - If you accept this execution method and the default codes, skip to step 17.
  Note: The Enter key is the default function processing key. It causes your program to test the function code that the end user enters, and execute the function. To override the Enter key as the default function processing key, perform step 15.
- The end user presses a function key, such as PF3. To assign one or more functions to a function key, perform step 12.
- The end user presses a special key, such as a PA key. To assign one or more functions to a special key, perform step 14.
Note: You can specify any combination of execution methods. For example, you can assign the E(xit) function to the F3 key, and other functions to function codes.

Rename the default function codes with alias codes
To rename any default function code with your own alternative, or alias, function code, go to a new line on the Alternate Functions screen and enter the following values in the following fields:

Program Input	Function	Reserved Function or Function Name
The new code, up to eight characters	A(lias)	The function whose code you are renaming, such as *Query or s

Program Input

Function

Reserved Function or Function Name

The new code, up to eight characters

A(lias)

The function whose code you are renaming, such as *Query or s

Press PF3 to return to the Online Express Menu.
Assign functions to function keys
To assign any function to a function key, select option 3, PF Key Functions. The PF Key Functions screen displays, and lets you assign functions to all 24 function keys. Initially, only the first 12 keys appear on the screen; to assign functions to function keys 13 through 24, select Actions List Next 12 PF Keys, or press Enter.

Note: If you defined trancodes for your MFS mapsets, do not assign functions to function keys.

Figure 5-7: PF Key Functions Screen
Press PF3 to return to the Online Express Menu.
Assign functions to CICS special keys
To assign functions to the Clear key and PA keys for a CICS application, select Actions, Special PF Keys, or enter spc in the Command field of the PF Key Functions screen to display the Special Key Definition screen. Complete the screen fields as follows:
1. Enter the teleprocessing function codes that you need in the Function field next to a key.
2. Enter the objects of the functions, such as the screen to send or the program to transfer to, in the Reserved Function or Function Name field.
Figure 5-8: Special Key Definition Screen
Change the default processing key
To override the Enter key as the default function processing key, enter the overriding key name, such as clear or pf10, in the Default Processing Key field on the Special Key Definition screen. The processing key causes your program to test the function code that the end user has entered, and execute the function.
Press PF3 to return to the Online Express Menu.

Special Considerations

Clearing screens with low-values

By default, the C(lear) function clears all I/O screen fields with spaces. Alternatively, you can clear repeated block row fields with low-values. To do so, display the Express Parms screen by entering p in the Command field of any Online Express screen, and change value of the Clear With Low-Values parameter to Yes.

Custom Program Functions

Tailor your programs

Without leaving Online Express, you can write custom program functions to supplement the predefined functions provided by Online Express. End users can execute custom functions just as they execute any predefined function.

Write local or global custom function logic

You can write functions specifically for one program, or for use throughout your application. A program-specific custom function is known as a local program stub; a custom function that you use throughout your application is known as a global program stub. Alternatively, you can write a function in a macro and invoke the macro in any program of any application. Stubs and macros are more fully described below:

Custom Function Component	Description
Local stub	Procedure Division and Data Division source that you write and execute specifically in one program. You write a local stub using the Specification Painter, which you access from the Alternate Functions, PF Key Definitions, or Special Key Definitions screen. A local stub can consist of a main paragraph, other paragraphs that the main paragraph performs, and Data Division source code for the paragraphs.
Global stub	Procedure Division source that you can execute in any program of an application. You write a global stub using the Program Painter, which you access from the Application Painter. A global stub can consist of one or more paragraphs.
Macro	Any Customization Facility source that you can execute in any program of any application. You write a macro in the USERMACS data set in your user Project and Group.

Custom Function Component

Description

Local stub

Procedure Division and Data Division source that you write and execute specifically in one program. You write a local stub using the Specification Painter, which you access from the Alternate Functions, PF Key Definitions, or Special Key Definitions screen. A local stub can consist of a main paragraph, other paragraphs that the main paragraph performs, and Data Division source code for the paragraphs.

Global stub

Procedure Division source that you can execute in any program of an application. You write a global stub using the Program Painter, which you access from the Application Painter. A global stub can consist of one or more paragraphs.

Macro

Any Customization Facility source that you can execute in any program of any application. You write a macro in the USERMACS data set in your user Project and Group.

Defining Custom Program Functions

To define custom program functions for applications, follow these steps:

Select the function execution method
Depending on how you want the end user to execute the function, decide which Online Express screen to use, as listed below:

Execution Method	Online Express Screen
Entering a function execution code	Alternate Functions
Pressing a function key	PF Key Functions
Pressing the Clear key or a PA key	Special Key Definitions

Execution Method

Online Express Screen

Entering a function execution code

Alternate Functions

Pressing a function key

PF Key Functions

Pressing the Clear key or a PA key

Special Key Definitions

Determine whether to write a stub or macro
Determine whether you want to write your function in a local stub, global stub, or macro. You can define any one of them to your program using any of the above screens.
- To define a local stub, perform step 3.
- To define a global stub, perform step 4.
- To define a macro, perform step 5.

Define local stubs
To define your custom function in a local stub, follow these steps:

Depending on how you want the end user to execute the function, display either the Alternate Functions, PF Key Functions, or Special Key Definition screen and complete it as follows:

Alternate Functions

Complete the screen as follows:

Enter a unique function execution code of up to eight characters in the Program Input field.
Leave the Reserved Function or Function Name field blank.
Enter e(dit local code) in the Function field. The Specification Painter screen displays, where you write the stub source code.

PF Key Functions

Complete this screen as follows:

Leave the Reserved Function or Function Name field blank.
Enter e(dit local code) in the Function field next to any function key listed on the screen. The Specification Painter screen displays, where you write the stub source code.

Special Key Definition

Complete this screen as follows:

Leave the Reserved Function or Function Name field blank.
Enter e(dit local code) in the Option field next to any key listed on the screen. The Specification Painter screen displays, where you write the stub source code.

Write the local stub as follows:
- To define the main paragraph, enter your COBOL, COBOL/2, or S-COBOL statements starting in column 12 and continue onto as many lines as you need. Do not enter a paragraph name; APS automatically generates one and displays it at the top of the Specification Painter screen. In the main paragraph, you can perform additional paragraphs that you write in the local stub. For information on writing S-COBOL statements, see the "S-COBOL Structures" topic in the APS Reference .
- To define an additional paragraph that the main paragraph performs, enter the APS keyword, PARA, in the KYWD column (columns 8-11) and the paragraph name starting in column 12 on the same line. On the following lines, enter your paragraph statements.
- After all paragraphs, define any Data Division source for the paragraphs, such as data items that the paragraphs reference. To do so, use APS Data Division keywords. For information, see the "Keywords for Program and Specification Painters" topic in the APS Reference .
  For example:
```
-KYWD-  12-*----20---*----30---*----40---*----50---*--
        statement
        .
        .
        .
        perform sub-para-name
 
 para   sub-para-name
        statement
        .
        .
        .
 ws
 01     group-level-data-item
        05  elementary-data-item
        .
        .
        .
```
When you finish writing the local stub, press PF3 to save it and return to the previous screen. Note that Online Express displays the value L(ocal code) in the Function field. To edit the stub, simply enter e(dit local code) in the Function field.

Define global stubs
To define your custom function in a global stub, follow these steps:

List the global stub name in your application definition. To do so, display the Application Painter screen and enter the following on a separate row anywhere in the definition:
- In the Programs field, enter the stub name. The name can have a maximum of eight characters. The first character must be alphabetic; others can be alphanumeric or the special characters @, $, or #.
- In the Screens field, enter the value *stub in the Screens field, to indicate that the stub has no associated screen.
Write the global stub using the Program Painter as follows:
- To display the Program Painter, enter s next to the stub name on the Application Painter.
- To define a paragraph, enter the PARA keyword in the KYWD column and your paragraph name in column 12 on the same line. On the following lines, enter your COBOL, COBOL/2, or S-COBOL paragraph statements. Do not use any other APS keywords in the paragraph. For information on writing S-COBOL statements, see the "S-COBOL Structures" topic in the APS Reference.
  For example:
```
-KYWD-  12-*----20---*----30---*----40---*----50---*--
 para   para-1-name
        statement
        .
        .
        .
 para   para-2-name
        statement
        .
        .
        .
```
Press PF3 to save your global stub and return to the Application Painter.

Depending on how you want the end user to execute the function, display either the Alternate Functions, PF Key Functions, or Special Key Definition screen and complete it as follows:

Alternate Functions

Complete this screen as follows:

Enter a unique function execution code of up to eight characters in the Program Input field.
Enter g (for global stub) in the Function field.
Enter the stub name in the Reserved Function or Function Name field.

PF Key Functions

Complete this screen as follows:

Enter g (for global stub) in the Function field next to any function key listed on the screen.
Enter the stub name in the Reserved Function or Function Name field.

Special Key Definition

Complete this screen as follows:

Enter g (for global stub) in the Option field next to any key listed on the screen.
Enter the stub name in the Reserved Function or Function Name field.

Define macros
To define your custom function in a macro, follow these steps:

Write your macro in the USERMACS data set in your user Project and Group. See the Customization Facility User's Guide for rules on writing macros.
List the macro name in your application definition. To do so, display the Application Painter screen and enter the following on any line above your application's program names:
- In the USERMACS field, enter the name of the USERMACS file that contains the macro. The name can have a maximum of eight characters. The first character must be alphabetic; others can be alphanumeric.
- In the Loc(ation) field, specify the program location where you plan to invoke the macro. For valid location values, see Paint the Application Definition.

Depending on how you want the end user to execute the function, display either the Alternate Functions, PF Key Functions, or Special Key Definition screen and complete it as follows:

Alternate Functions

Complete this screen as follows:

Enter a unique function execution code of up to eight characters in the Program Input field.
Enter the macro invocation symbol $ in the Function field.
Enter the macro name in the Reserved Function or Function Name field.

PF Key Functions

Complete this screen as follows:

Enter the macro invocation symbol $ in the Function field next to any key.
Enter the macro name in the Reserved Function or Function Name field.

Special Key Definition

Complete this screen as follows:

Enter the macro invocation symbol $ in the Option field next to any key.
Enter the macro name in the Reserved Function or Function Name field.

Mapping Screens to Database Fields

You must map your screen or screen fields to the appropriate fields in your database. To help you do so quickly, Online Express displays all fields that you defined when you painted your screen or screen. You simply specify each screen field's corresponding database field, and indicate whether the screen field is an input field, an output field, or both.

To map screen fields to your database fields, follow these steps:

Ensure that you have done the following:
- Listed the components of your application on the Application Painter screen.
- Painted your screens using the APS Screen Painter.
- Imported your program subschema(s) using the APS Database Importers.
Display the Field Mapping screen
Select option 4, Field Mapping, from the Online Express Menu to display the Field Mapping screen. The screen displays all screen fields that you defined in the Screen Painter. Note that APS prefixes all field names with their associated screen name.

Figure 5-9: Field Mapping Screen
Specify whether fields are input/output
Specify whether the screen fields are input, output, or input/output fields by entering i(nput), o(utput), or b(oth) next to each field in the I/O/B column. Leave this column blank for function fields, system message fields, and savekey fields, because they do not have corresponding database fields.
Specify database field names
Enter each screen field's corresponding database field name in the Program Field column.

Alternatively, to save yourself some typing, copy all the screen field names to the Program Field column by entering an asterisk (*) in the Command field. Online Express copies all screen field names--except function, system message, and savekey fields--without their prefixes, to the Program Field column. In addition, Online Express enters the value b(oth) in the I/O/B column for all copied fields. Then, modify the names as necessary. To add a prefix to some or all fields simultaneously, use the prefix command.

Enter any of the following prefix command formats in the Command field:

pre fldprefix	Adds fldprefix to fields on all lines
pre fldprefix m n	Adds fldprefix to fields from line m through line n
pre fldprefix n*	Adds fldprefix to fields from line 1 through line n
pre fldprefix n *	Adds fldprefix to fields from line n through the last line

Special Considerations

Qualify fields that belong to multiple records
If one of your database fields exists in multiple database records, you must qualify the field to indicate which record it belongs to. To do so, insert a line with the i(insert) line command and on the following line, enter the word of followed by the record name. For example:
```
Screen Field          I/O/B     Program Field
--------------------    -       -------------------
CSINFO-ORDER-NO         B       CO-ORDER-NO
                                 OF SALES-REC
```

Clear the screen
To clear some or all of the values you entered, enter the reset command in any of the following formats in the Command field:

reset	Clears values on all lines
reset m n	Clears values from line m through line n
reset n*	Clears values from line 1 through line n
reset n *	Clears values from line n through the last line

Control Points

Use control points to tailor default processing logic

Without leaving Online Express, you can write and execute custom processing logic to supplement or override the default logic that Online Express generates. You execute custom logic at any of several APS-provided locations in your program, known as program control points. Control points let you add logic at such locations in the processing logic as:

Upon program invocation
Before sending a screen
Before evaluating program functions
Before and after moving records between the database and the screen
Before transferring control to another program
Before terminating the program normally or abnormally
Other locations, depending on which functions you define for your program

Control points for database calls

In addition, you can add processing logic before and after database calls. For information, seeCustom Logic at Database Call Control Points.

Write local or global custom processing logic

You can write local custom logic specifically for one or more control points in a program, or global custom logic for use throughout your application. You execute any local or global logic at any control point. You write local and global logic in any of the following components in your program or application:

Custom Logic Component	Description
Local stub	Procedure Division and Data Division source that you write and execute specifically in one program. You write a local stub using the Specification Painter, which you access from the Control Points screen. A local stub can consist of a main paragraph, other paragraphs that the main paragraph performs, and Data Division source code for the paragraphs.
Global stub	Procedure Division source that you can execute in any program of an application. You write a global stub using the Program Painter, which you access from the Application Painter. A global stub can consist of one or more paragraphs.
Paragraph	A Procedure Division paragraph and Data Division source that you write specifically for one program and execute at one or more control points. You write a paragraph in the Specification Painter, which you access from the Control Points screen.
Macro	Customization Facility source that you can execute in any program of any application. You write a macro in the USERMACS data set in your user Project and Group.

View contol points on the Control Points screen

The set of control points that might appear in your program is shown below. Because programs vary, you will see a different subset of control points from program to program, depending on which functions you define for them. To view the control points in your program, you display the Control Points screen. In addition, you can look in your generated program source to see where the control points occur; APS generates comments that identify them that you can activate or deactivate. To activate these comments, set the value of the Control Points Comments field to yes on the Express Parms screen. To access the Express Parms screen, enter p in the Command field on the Online Express Menu. The complete set of control points is as follows:

Control Point	Location in Program
After-Receive-Para	After entering a program, regardless of invocation mode.
Post-Screen-Read	After a screen-invoked program receives its screen.
Transid-Invoked-Para	After a transid-invoked program is invoked.
Program-Invoked-Para	When APS displays the screen of a program invoked by the XCTL or MSG-SW function.
Pre-Term	Before APS terminates the program.
After-Enter-Check	After the end user presses the processing key (the Enter key is the default), and before the PRE-FUNCTION-TEST paragraph executes.
Pre-Function-Test	Before APS evaluates all functions except the Terminate, or Exit, function.
Pre-Branch	Before each MSG-SW, XCTL, or Call function executes.
Ed-Error-Pre-Send	Before APS send a screen whose field edits have failed.
General-Pre-Send	After APS checks all functions, and before the TP-SEND call executes, when invocation mode is screen-invoked.
Before-Send-Para	Before APS sends the screen, regardless of invocation mode.
Pre-Screen-To-Rec	Before APS performs the MOVE-SCREEN-TO-REC paragraph.
Post-Screen-To-Rec	After APS performs the MOVE-SCREEN-TO-REC paragraph, and the Update or Add function executes.
Pre-Rec-To-Screen	Before APS performs the MOVE-REC-TO-SCREEN paragraph.
Post-Rec-To-Screen	After APS performs the MOVE-REC-TO-SCREEN paragraph, and after the Query function executes.
Pre-RB1-Row-To-Rec	Before the Add or Update function executes for a repeated record block row, and before screen fields move to database fields. APS uses the subscript CTR to reference repeated block rows.
Post-RB1-Row-To-Rec	Before the Add or Update function executes for a repeated record block row, and after screen fields move to database fields. APS uses the subscript CTR to reference repeated block rows.
Pre-Rec-To-RB1-Row	After the Query or Forward function executes for a repeated record block row, and before database fields move to screen fields. APS uses the subscript CTR to reference repeated block rows.
Post-Rec-To-RB1-Row	After the Query or Forward function executes for a repeated record block row, and after database fields move to screen fields. APS uses the subscipt CTR to reference repeated block rows.
Error-Send-And-Quit	When a program terminates abnormally, such as when a database call fails when the Database Call Tailoring screen's Abort On Error parameter is set to y.
Misc-User-Paragraphs	A location where you can write and store any number of paragraphs that you can perform at any control point in your program. Write all your paragraphs in one file in this location.

Inserting Logic at Control Points

To insert your custom logic at control points, follow these steps:

From the Online Express menu, display the Control Points screen by selecting option 5, Control Points.

Figure 5-10: Control Points Screen
Decide how to implement the control point
Determine whether you want to write your custom logic in a local stub, global stub, macro, or paragraph:
- To define a local stub, perform step 3.
- To define a global stub, perform step 4.
- To define a macro, perform step 5.
- To define a paragraph, perform step 6.
Define local stubs
To define your control point logic in a local stub, enter e(dit local code) in the Action field next to the control point where you want to execute the stub. The Specification Painter displays, where you write the stub as follows:
1. To define the main paragraph, enter your COBOL, COBOL/2, or S-COBOL statements starting in column 12 and continue onto as many lines as you need. Do not enter a paragraph name; APS automatically generates one and displays it at the top of the Specification Painter screen. In the main paragraph, you can perform additional paragraphs that you write in the local stub. For information on writing S-COBOL statements, see the "S-COBOL Structures" topic in the APS Reference.
  - To define an additional paragraph that the main paragraph performs, enter the APS keyword, PARA, in the KYWD column (columns 8-11) and the paragraph name starting in column 12 on the same line. On the following lines, enter your paragraph statements.
  - After all paragraphs, you can define Data Division source for the paragraphs, such as data items that the paragraphs reference. To do so, use APS Data Division keywords. For information, see the "Keywords for Program and Specification Painters" topic in the APS Reference.
    For example:
```
-KYWD-  12-*----20---*----30---*----40---*----50---*--
        statement
        .
        .
        .
        perform sub-para-name
 
 para   sub-para-name
        statement
        .
        .
        .
 ws
 01     group-level-data-item
        05  elementary-data-item
        .
        .
        .
```
2. When you finish writing the local stub, press PF3 to save it and return to the previous screen. Note that Online Express displays the value L(ocal code) in the Function field. To edit the stub, simply enter e(dit local code) in the Function field.
Define global stubs
To define your control point logic in a global stub, follow these steps:
1. List the global stub name in your application definition. To do so, display the Application Painter screen and enter the following on any line above your application's program names:
  - In the Programs field, enter the stub name. The name can have a maximum of eight characters. The first character must be alphabetic; others can be alphanumeric or the special characters @, $, or #.
  - In the Screens field, enter the value *stub in the Screens field, to indicate that the stub has no associated screen.
2. Write the global stub using the Program Painter as follows:
  - To display the Program Painter, enter s next to the stub name on the Application Painter screen.
  - To define a paragraph, enter the PARA keyword in the KYWD column and your paragraph name in column 12 on the same line. On the following lines, enter your COBOL, COBOL/2, or S-COBOL paragraph statements starting in columns 12. Do not use any other APS keywords in the paragraph. For information on writing S-COBOL statements, see the "S-COBOL Structures" topic in the APS Reference.
    For example:
```
-KYWD-  12-*----20---*----30---*----40---*----50---*--
 para   para-1-name
        statement
        .
        .
        .
 para   para-2-name
        statement
        .
        .
        .
```
3. Press PF3 to save your global stub and return to the Application Painter.
4. Execute the stub at any control point by entering g(lobal code) in the Action field next to the control point, and the stub name in the Exit Name field.
Define macros
To define your control point logic in a macro, follow these steps:
1. Write your macro in the USERMACS data set in your user Project and Group. See the Customization Facility User's Guide for rules on writing macros.
2. List the macro name in your application definition. To do so, display the Application Painter screen and enter the following on any line above your application's program names:
  - In the USERMACS field, enter the name of the USERMACS file that contains the macro. The name can have a maximum of eight characters. The first character must be alphabetic; others can be alphanumeric.
  - In the Loc(ation) field, specify the program location where you plan to invoke the macro. For valid location values, see Paint the Application Definition.
3. Invoke the macro at any control point by entering the macro invocation symbol $ in the Action field next to the control point, and the macro file name in the Exit Name field.
Define paragraphs
To define your control point logic in one or more paragraphs, follow these steps:
1. Write the control point paragraph(s) using the Specification Painter. To do so, enter e (for edit) next to the Misc-User-Paragraphs control point on the Control Points screen and write the paragraphs according to the following rules:
  - For each paragraph, enter the PARA keyword in the KYWD column and your paragraph name in column 12 on the same line. On the following lines, enter your COBOL, COBOL/2, or S-COBOL paragraph statements starting in column 12. Do not use any other APS keywords in the paragraph. For information on writing S-COBOL statements, see the "S-COBOL Structures" topic in the APS Reference.
  - After all paragraphs, you can define Data Division source for the paragraphs, such as data items that the paragraphs reference. To do so, use APS Data Division keywords. For information, see the "Keywords for Program and Specification Painters" topic in the APS Reference.
    For example:
```
-KYWD-  12-*----20---*----30---*----40---*----50---*--
 para   para-name
        statement
        .
        .
        .
        perform sub-para-name
 
 para   sub-para-name
        statement
        .
        .
        .
 ws
 01     group-level-data-item
        05  elementary-data-item
        .
        .
        .
```
2. When you finish writing the paragraph(s), press PF3 to save it and return to the previous screen. Note that Online Express displays the value L(ocal code) in the Action column. To edit the paragraphs, simply enter e(dit local code) in the Action column.
3. Perform the paragraph at any control point by entering p in the Action column next to the control point, and the paragraph name in the Exit Name column. To pass arguments to the paragraph, code them next to the paragraph name without parentheses. For example:
```
paraname arg1 arg2 arg3
```
  For more information, see the "TP-PERFORM" topic in the APS Reference.