Introduction to Using PxPlus

Basic Concepts

The information below explains the structural concepts of PxPlus. Some of the terminology will be familiar to developers with experience in other Business Basics; however, PxPlus has several unique properties. Before attempting to program in PxPlus, it is a good idea to take some time to understand the different aspects of the language.

PxPlus Session

The PxPlus environment comprises a Command mode and an Execution mode. When in Command mode, PxPlus will be waiting for a directive or statement to be entered. Execution mode begins once a RUN or a CALL directive is used to execute a program.

By default, PxPlus initializes in Command mode, as indicated by the Command mode prompt '->'.

Directives can be entered in Command mode. If a directive does not include a leading line number, it is executed immediately; otherwise, the statement is used in the construction of a program.

When a statement is inserted into a program, the prompt changes from '->' to '-:' to indicate that the program has been changed but not saved. When PxPlus is in Execution mode, it receives and executes all the statements that constitute a program. The program remains in Execution mode until completed (via the STOP or END directive), an error occurs, or it is interrupted via a BREAK or ESCAPE instruction.

The PxPlus session can be terminated using the BYE, QUIT or RELEASE directives.

Directives and Statements

In PxPlus, all processing is controlled by the use of Directives - commands that tell the system what task is to be performed. Each program statement (line of code) consists of one or more directives. When PxPlus executes a program, it executes all directives contained in a statement from left to right and then proceeds to the next line. Some directives provide the ability to alter the normal flow of execution.

The general format of a program statement includes a unique line number (optional), the directive indicating the operation to perform, parameters and comments. Parameters are syntax elements, keywords, operators and arguments that can be used to further define a directive's operation.

Example:

The complete syntax for the CLOSE directive appears as:

close (chan [,err=stmtref])[,(chan[,err=stmtref])...]

Depending on the statement, it is possible to exclude all but the mandatory parameters from the directive:

close (14)

See the Directives Help section for the complete list of PxPlus directives in alphabetical order.

System Functions

A PxPlus System Function consists of a three-character function name followed by an open parenthesis, the parameter(s) for the function, an optional error transfer, and a close parenthesis:

Example:

and(A$,B$,err=0300)

The number and type of parameters vary from function to function. All may include the ERR= option (even those where an error is unlikely).

See the System Functions Help section for the complete list of PxPlus system functions in alphabetical order.

Data and Variables

PxPlus supports two basic types of data -- Numeric data and String data. Numeric data consists of numeric values such as account balances, prices and quantities. String data consists of textual information such as account names and descriptions. A PxPlus program maintains and processes its data using Variables - numeric variables to store numeric values and string variables to store textual information. The language includes various internally defined variables for providing system information such as the date and time.

You can use system variables wherever normal program variables would be used; however, you cannot modify them.

See the System Variables Help section for the complete list of PxPlus system variables in alphabetical order.

Note:
All system variables have reserved three-character names and do not have a trailing $ dollar sign; e.g. CTL.

To avoid potential conflicts with the reserved list (since PxPlus might reserve more three-character variables in the future), it is strongly advised that you do not use three-character variable names.

Mnemonics

Mnemonics are used to control output to terminals and printers. A mnemonic instruction is enclosed in single quotation marks.

Example:

print @(5,5),'CL' ! Clears screen - line 5 to its end, starting at column 5
open (30)PRINTER$
print (30)'FF', ! Form-feed instruction to PRINTER$ on channel 30

See the Mnemonics Help section for the complete list of PxPlus mnemonics in alphabetical order. See also the MNEMONIC directive.

System Parameters

System Parameters are normally used at start-up to define the system's operation under PxPlus. For example, the 'BY' system parameter is used to define the base year for the JUL( ) and DTE( ) functions. Like mnemonics, system parameters are enclosed in single quotation marks.

See the System Parameters Help section for the complete list of PxPlus system parameters in alphabetical order. See also the PRM( ) function and the PRM system variable.

Graphical Control Objects

Graphical Control Objects in PxPlus programs are used to display information, input data, and handle event processing.

The following Directives are used to create and maintain the various control object types:

Directive	Description
BUTTON	Used to create and control buttons on the screen.
CHART	Used to create two and three dimensional chart illustrations in a graphical application.
CHECK_BOX	Used to create check box control objects on the screen.
DROP_BOX	Used to create and manipulate drop box control objects on the screen.
GRID	Used to create a grid or table of cells in columns and rows; i.e. a spreadsheet input format.
LIST_BOX	Used to create and control list boxes on the screen.
MULTI_LINE	Used to create and control a Multi-Line input region on the screen. Multi-Line input is used to enter or display text.
RADIO_BUTTON	Used to create and control a group of radio button control objects on the screen. A radio button group is a series of related circular/radio-knob buttons of which only one button can be active at a time.
H_SCROLLBAR	Used to create a horizontal scrollbar control object on the screen.
V_SCROLLBAR	Used to create a vertical scrollbar control object on the screen.
TRISTATE_BOX	Used to create and control a tristate box control object. A tristate box is a check box in which the user can toggle between three states: ON to select an option, OFF to disable it, or your choice of a third state.
VARDROP_BOX	Used to create and control a variable drop box on the screen. A variable drop box normally displays a single line on the screen with a down arrow on the right side and allows variable input.
VARLIST_BOX	Used to create and control a variable list box on the screen. The user can select any element from a list of items associated with the variable list box or can enter any other value.

Note:
In Windows, the above directives use Graphical Device Interface (GDI) resources/handles that are only released when the window they are in is dropped or cleared.

The attributes of a control object can be referenced and determined by the use of Property Names (e.g. 'Height, 'Font$, 'Text$, 'TextColor$, etc.). The object itself is defined by a numeric variable containing the CTL value associated with the control followed by an apostrophe and the property. See Apostrophe Operator.

For each graphical control object, a list of properties and their descriptions is included with the Help for the associated control directive. For example, a list of Button Properties is available by expanding the Help node for the BUTTON directive. A list of Chart Properties is available by expanding the Help node for the CHART directive, and so on. See Graphical Control Objects.

Graphical control objects can also be created by using the NOMADS toolset for GUI-based application design/development. See NOMADS Development and Creating Panel Controls.

Specialty Files

PxPlus supports the use of a set of device files that are designed for Special File Handling. When these files are used in an OPEN directive, the system recognizes and processes them internally in the language at run time.

Special Command Tags

PxPlus supports the use of Special File Command Tags, which are used to modify paths and filenames for specific I/O uses in PxPlus. They may include a series of semi-colon separated parameters to be processed at run time. Some of these tags are supported only in specific operating environments.

Object Oriented Programming

The PxPlus language has been extended to support all of the key design principles of Object Oriented Programming (OOP). The three basic principles of OOP are Encapsulation, Inheritance and Polymorphism. These concepts provide a major part of the framework used to create and interact with objects. See Concepts and Terminology.

PxPlus OOP objects are defined through the use of Classes. A Class defines the name given to the object definition, as well as the object's properties and methods. Properties are the data portion of the object, consisting of fields or variables. Methods (or functions) are the actions that the object will perform. The defined properties/methods are accessible via the Apostrophe Operator.

The following Directives and Functions are used to handle OOP mechanisms in PxPlus:

DEF CLASS	Defines the object class.
DROP CLASS	Deletes class definition and all related information.
DROP OBJECT	Deletes an object.
FUNCTION	Declares functions or methods for the object.
LIKE	Specifies other objects that this object inherits from.
LOAD CLASS	Change name of an existing class.
LOCAL	Declares internal data/properties for the object.
NEW( )	Creates an object instance.
PRECISION	Sets default program precision for use within the object.
PROGRAM	Defines the default program that contains the object logic.
PROPERTY	Declares data/properties for the object.
REF( )	Controls reference counts.
STATIC	Dynamically declares LOCAL variables.

Accessing Data Files

PxPlus supports a wide variety of file formats: proprietary/non-proprietary, program, link, device, data, etc. When referring specifically to Data Files in PxPlus, the primary file types and record formats are defined as follows:

Serial

Records can vary in length and are typically accessed in a sequential manner from beginning to end.

Indexed

Records are the same length and are accessed by index number.

Keyed

Records are accessed via key, a string of characters used to identify the records in a file. Keyed files are the most common data file type used by applications written in PxPlus.

Three Keyed formats are supported: FLR (fixed-length records), VLR (variable-length records), and EFF (enhanced file format).

See EFF vs. VLR File Formats for an explanation of these two file formats.

Keyed files are also considered to be:

Direct	Consisting of a single key per record (FLR/VLR)
Keyed	Consisting of one or more keys per record (FLR/VLR, EFF)
Sort	Consisting of keys but no data (FLR/VLR, EFF)

Access to a data file is controlled by the use of a Channel or Logical File Number. The link between data file and channel is established using the OPEN directive. All subsequent input and output to the file uses the same channel, which cannot be reused until the file is closed (via CLOSE, START, BEGIN, or by termination of the user session).

The following Directives are used to create, delete and rename data files:

Directive	Description
ADD INDEX	Add key to keyed file.
CREATE TABLE	Create keyed file (EFF).
DIRECT	Create file with keyed access.
DIRECTORY	Create subdirectory.
DROP INDEX	Drop key from keyed file.
ERASE	Delete file/directory from system.
INDEXED	Create indexed file.
KEYED	Create single/multi-keyed file.
RENAME	Change a file's name.
RENAME..INDEX	Rename keys in keyed file.
SERIAL	Create a sequential file.
SORT	Create file for sorting.

The following Directives are used for file input/output and access:

Directive	Description
CLOSE	Close file.
EXTRACT	Read and lock data.
FIND	Locate and read data.
LOCK	Reserve file for exclusive use.
OPEN	Open a file for processing.
PRINT	Display information.
PURGE	Clear data from a file.
READ	Read data from file.
REMOVE	Delete record from file.
UNLOCK	Remove exclusive use from file.
WRITE	Add/update data in file.

Several System Functions are used for file processing, including:

System Function	Description
FIB( )	Return file information block.
FID( )	Return file information descriptor.
FIN( )	Return file information.
IND( )	Return next record index.
KEC( )	Return key of current record.
KEF( )	Return first key of file.
KEL( )	Return last key of file.
KEN( )	Return key after next.
KEP( )	Return prior record's key.
KEY( )	Return key of next record.
KGN( )	Generate record key.
RCD( )	Return next record.
RNO( )	Return next record number.

Error Report and Handling

If an error condition is detected during the execution of a program, the associated error code(s) can be obtained using the ERR and RET system variables. The line number of the last system-detected error can be determined by the ERS variable. The MSG( ) function provides a description for any known PxPlus error in the range of 0 to 255. The 'ES' system parameter, if enabled, can be used to display any operating system error messages, along with the normal PxPlus error, from a Command prompt.

By default, when an error occurs in an application, PxPlus will stop processing, display the error code/message and statement where it occurred, and then return to Command mode. Most PxPlus directives and functions, for which errors are anticipated, provide an error transfer option denoted by an ERR=stmtref option in the syntax description (stmtref represents a number or statement label to which to transfer control). Error handling can also be specified via the SETERR directive.

The ERROR_HANDLER directive is used to assign a generic application-wide, error-handling program that will intercept any "un-trapped" errors in an application.

PxPlus features several utilities and language elements that will help you locate and handle errors during the coding, testing and debugging stages of the development cycle. See Error Handling and Debugging and Error Messages and Codes.

Introduction to Using PxPlus

Note: In Windows, the above directives use Graphical Device Interface (GDI) resources/handles that are only released when the window they are in is dropped or cleared.

See Also

Note:
In Windows, the above directives use Graphical Device Interface (GDI) resources/handles that are only released when the window they are in is dropped or cleared.