APPX Runtime Subroutine API

These APIs can be used by an APPX designer to interact with the APPX Runtime Application (---) to gain access to extra functionality. This page only lists the APIs that were introduced in Release 5.1. For a list of all APIs in the current release, go to the full list.

Overview

Release 5.1.0 of the APPX Utility includes a new standardized designer API which can be used to gain access to extended functionality from within an APPX application. This API provides APPX Designers with a robust set of subroutines which can be called to do a variety of tasks. This API replaces the older subroutines that have been informally used, and all designers are encouraged to begin using the new subroutines.

General Information

All of these new subroutines are defined in the (---) application and begin with a period (.). They all use a standard call interface and use the same framework for returning results and reporting errors. They are grouped by name prefix so that related subroutines are grouped together by function. Data is passed into and returned from these subroutines by use of the PASS statement. Failure information is returned by use of a work field with the same name as the subroutine. This failure code field is tokenized so you can scan to see the failure reasons that can be returned. Note that the work field has a scope of 'Detached', and so will retain it's value from invocation to invocation, as well as across all invocation types.

If the subroutine accepts parameters (i.e., READ, WRITE, APPEND to --- .STREAM OPEN), the parameters are case insensitive.

If the subroutine has required parameters and you do not PASS the correct number of parameters, the subroutine will issue a CANCEL identifying which parameter was missing.

General Subroutines

Application Routines

.BEGIN INITIAL SETUP

Changes the current application to the 'Initial Setup' phase.

.BEGIN LIVE OPERATIONS

Changes the current application to the 'Live Operations' phase.

.BEGIN RECOVERY PROCESSING

Changes the current application to the 'Recovery Processing' phase.

.SELECT DATABASE

Switches to the specified database.

Utility Routines

.UTIL ADD USER

Adds a user to the Appx User file.

.UTIL ADD HOOK

Adds a record to the Hook file.

.UTIL CHECK SECURITY

Checks the security code for the specified user.

.UTIL CHG AUX PASS

Changes the Auxiliary password for the specified user.

.UTIL CHG HOOK

Changes fields on the Hook File.

.UTIL CHG USER

Changes fields on the Appx User File.

.UTIL CLEAR PASS LIST

Clears any unfilled PASS requests.

.UTIL COMPILE PROC

Compiles the specified Process Type/Name or Application.

.UTIL DEL USER

Deletes a user from the Appx User File.

.UTIL DEL HOOK

Deletes a record from the Hook File.

.UTIL FIELD GET

Retrieves the value of the specified field name.

.UTIL FIELD SET

Sets a value into the specified field name.

.UTIL GET EM NAME

For a given Process Type/Name, returns the Em name.

.UTIL GET HOOK RECORDS

Copies the engine Hook records into a temporary file for modification.

.UTIL LOAD STACK FILE

Loads --- STACK with the current process stack.

.UTIL MAKE DYNAMIC KEY

Not Implemented

.UTIL MOD SCROLL BEHAV

This subroutine allows the user to select a record on a scrolling display by just clicking it.

.UTIL PROCESS DD

Processes the Data Dictionary for the selected Application or File.

.UTIL PROCESS QRY REC

Writes the current record to the Query pointer file.

.UTIL PUT HOOK RECORDS

Activates the hooks in the temporary file.

.UTIL SLEEP

Pauses for the specified number of seconds.

.UTIL SLEEP WITH TIMER

Pauses for the specified number of seconds with a countdown timer.

.UTIL SWITCH USER

Changes to a different user.

.UTIL TIMEOUT EXIT

Exits or logout a user after a set timeout period.

.UTIL TIMEOUT SET

Sets the keyboard timeout value.

.UTIL UPDATE DOCUMENT

Update process documentation via ILF

Web Processing Routines

.IMPORT CGI DATA

Populates Appx Variables from STDIN.

WIDGET Routines

.WIDGET APPLY THEME

Applies a GUI Theme to the current image.

.WIDGET CNV CLR TO RGB

Converts an alpha/hex color code to decimal.

.WIDGET CNV RGB TO CLR

Converts a decimal color code to alpha/hex.

.WIDGET DEL BY NAME

Deletes selected widgets.

.WIDGET DEL MODE BTN

Deletes the mode buttons from the toolbar.

.WIDGET DEL SCROLL BTN

Deletes the scroll buttons from the toolbar.

.WIDGET DEL STD MENUS

Deletes the standard pull down menus.

.WIDGET HIDE BY NAME

Hides selected widgets.

.WIDGET HIDE MODE BTN

Hides the mode buttons on the toolbar.

.WIDGET HIDE SCROL BTN

Hides the scroll buttons on the toolbar.

.WIDGET HIDE STD MENUS

Hides the standard pull down menus.

.WIDGET MISSING THEME

Finds all Inputs/Menus that do not use .WIDGET APPLY THEME.

.WIDGET SET FROM MWDGT

Copies the memory file to --- WIDGET.

.WIDGET SET INTO MWDGT

Copies the current --- WIDGET file to a memory file.

.WIDGET SET THEME

Sets the current Theme Name.

.WIDGET SHOW BY NAME

Shows previously hidden widgets.

.WIDGET SHOW MODE BTN

Shows previously hidden mode buttons on the toolbar.

.WIDGET SHOW SCROL BTN

Shows previously hidden scroll buttons on the toolbar.

.WIDGET SHOW STD MENUS

Shows the previously hidden standard pull down menus.

.WIDGET VIEW RUNTIME

Shows properties of the current --- WIDGET file.

Data Manipulation Subroutines

Conversion Routines

.CONVERT BYTES TO HEX

Converts a field to hexadecimal characters.

.CONVERT HEX PR TO NUM

Converts a hex pair of alpha characters to a decimal number.

.CONVERT NUM TO HEX PR

Converts a decimal number to a hex pair of alpha characters.

.CONVERT SPLIT NUMBER

Splits a number into its whole and fractional parts.

.CONVERT TEXT TO HTML

Converts a text field to HTML encoding

.CONVERT TRANSLATE

Converts a string from one language to another.

Text Routines

.TEXT CREATE PAD

Fills a field with a single character.

.TEXT CUT AT POS

Removes characters from a text/alpha field.

.TEXT FIND

Find the position of text in a text/alpha field.

.TEXT FIND AND REPLACE

Find and replace text in a text/alpha field.

.TEXT GET LENGTH

Determine the length of a text/alpha field.

.TEXT INSERT AT POS

Inserts characters into a text/alpha field.

.TEXT LOWER TO UPPER

Convert lower case to upper case in a text/alpha field.

.TEXT PARSE LINE

Parse a string into separate fields.

.TEXT UPPER TO LOWER

Convert upper case to lower case in a text/alpha field.

System Information Subroutines

Server Environment Routines

.ENV GET APPXPATH

Returns the path to the location of Appx data files.

.ENV GET CMD LINE PARM

Returns the value of a command line parameter.

.ENV GET CONFIG INFO

Populates PDF fields with configuration information.

.ENV GET ENV VARIABLE

Returns the value of an environment variable.

.ENV GET OS TYPE

Return the type of operating system Appx is running on.

.ENV GET PARENT PROC

Returns the name and type of the parent process.

.ENV GET PATH NAME

Returns the pathname of the requested APPX data file.

.ENV GET PATH SEP

Returns the directory separator character of the host operating system.

.ENV GET SCREEN SIZE

Returns the size of the Appx screen in rows and columns.

.ENV SET ENV VARIABLE

Sets the value of an environment variable (not yet implemented).

.ENV VIEW LICENSE INFO

Displays the APPX license info for the current application.

Client Routines

.CLIENT CHECK FOR GUI

Returns a flag to indicate if the user is running the Desktop Client.

.CLIENT CHECK VERSION

Returns the version of the Desktop Client.

.CLIENT DOWNLOAD FILE

Downloads a file to the user's PC.

.CLIENT GET CLIPBOARD

Gets the current content of the system clipboard.

.CLIENT GET CONSTANT

Returns the value of a client constant

.CLIENT LOAD URL

Loads a URL, document, runs a command on the user's PC or changes a client setting.

.CLIENT PLAY SOUND

Plays a .wav file on the user's PC.

.CLIENT SET CLIPBOARD

Puts data on the system clipboard.

.CLIENT UPLOAD FILE

Uploads a file from the Client to the server.

File System Utilities Subroutines

File Manipulation Routines

These subroutines provide you with a way to manipulate files on the file system without having to check the O/S type (i.e., using 'cp' vs 'copy', or different kernel calls).

.FILE COPY

Copies a file from one location to another, creating any required directories.

.FILE CREATE

Creates the specified file.

.FILE CREATE ARCHIVE

Creates an archive of the specified files, in either TAR or TGZ format.

.FILE DELETE

Deletes the given file from the filesystem.

.FILE EXISTS

Tests for the existence of the given file in the filesystem.

.FILE EXTRACT ARCHIVE

Extracts all the files from a previously created archive.

.FILE MAKE DIR

Creates the given directory and parent directories in the filesystem.

.FILE MOVE

Moves a file or directory from one location to another, creating any required directories

.FILE RESTRUCT

Restructures the specified file.

.FILE SPLIT FILENAME

Splits the filename from the file extension and returns both.

.FILE SPLIT PATHNAME

Splits the filename from the path and returns both.

Stream File Routines

The stream routines provide a way to work directly with text files, or to get the standard output of a command (via pipes).

.STREAM CLOSE

Closes a file stream and frees up the stream resources for that file.

.STREAM CLOSE ALL

Closes all file streams and frees up the stream resources for those files.

.STREAM OPEN

Opens a stream to the given file creating the file and path as needed.

.STREAM READ

Read data from the given stream.

.STREAM WRITE

Write data to the given stream.

-- PeteBrower - 2011-08-12