APPX Runtime Subroutine API

This page lists all the available API's in the current version of Appx. Various API's have been released at different times and are documented in the release notes for that release, this page lists all of them in one location. The initial set of API's was released in version 5.1.

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 RBS

Checks the security access for the specified user when Role Based Security is used.

.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 COMPUTE HASH

Computes the SHA-2 hash value of the given string

.UTIL DEL USER

Deletes a user from the Appx User File.

.UTIL DEL HOOK

Deletes a record from the Hook File.

.UTIL EMAIL

Sends an Email.

.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 GET MESSAGES

Populates the --- MESSAGES file with any messages that were issued

.UTIL KILL SESSION

Cancels the specified process

.UTIL LOAD STACK FILE

Loads --- STACK with the current process stack.

.UTIL MAKE DYNAMIC KEY

Not Implemented

.UTIL MARK SET

Marks a process so you can return to it immediately via .UTIL MARK REWIND

.UTIL MARK REWIND

Returns immediately to a previously marked process, closing all processes in between.

.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 SECR REST

Restores Security codes from the archive

.UTIL SECR SAVE

Saves Security codes to the archive

.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 SUBR CLOSE

Closes the subroutine you created using .UTIL SUBR CREATE

.UTIL SUBR CREATE

Adds a subroutine to the specified application.

.UTIL SUBR DELETE

Deletes a subroutine from the application.

.UTIL SUBR WRITE ILF

Writes ILF code to a subroutine in the Application.

.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

XML Processing Routines

.XML IMPORT

Processes an XML file and optionally imports it.

.XML PURGE

Deletes the work files used by a particular import session.

.XML WRITER OPEN

Creates and opens an XML file on the server and adds <?xml?> to it.

.XML WRITER CLOSE

Closes an XML file and frees up memory used by XML Writer.

.XML WRITER ELEM START

Opens an element in an XML file.

.XML WRITER ELEM END

Closes the most recent opened element in an XML file

.XML WRITER ADD DATA

Adds data to the most recent opened element in an XML file.

.XML WRITER CDAT START

Opens a cdata element in an XML file

.XML WRITER CDAT END

Adds cdata end tag to an XML file

.XML WRITER ADD ATTR

Adds an attribute name, value pair to the most recent opened element in an XML file.

JSON Processing Routines

.JSON PARSE

Processes a JSON string and imports it.

.JSON PARSE FILE

Processes a JSON file and imports it.

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 COUNT ROWS

Returns the count of selected rows in the specified table widget

.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 RELOAD DATASRC

Reloads all the data in a Table Widget

.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 SET TOOLTIP

Sets or clears the tooltip for selected widgets

.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 HTML TO TEXT

Converts HTML text to plain APPX text

.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.

.CONVERT TO BASE64

Converts Appx raw data to Base64 data.

.CONVERT FROM BASE64

Converts Base64 data to Appx raw data.

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 FROM UNICODE

Transcodes the specified text from a Unicode field to a RAW Field.

.TEXT GET LENGTH

Determine the length of a text/alpha field.

.TEXT GET UNINAME

Returns the name of the given Unicode character.

.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 SET UNINAME

Returns the named Unicode character

.TEXT TO UNICODE

Transcodes the RAW text to a Unicode field.

.TEXT UNICODE COMP

Compares 2 Unicode 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 ENCODINGS

Populates the --- ENCODINGS file.

.ENV GET ENV VARIABLE

Returns the value of an environment variable.

.ENV GET ENV (ALL)

Returns the value of all environment variables.

.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 DISPLAY FILE

Downloads and opens a file on the user's PC.

.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 CSV EXPORT

Exports the specified File to CSV format.

.FILE CSV IMPORT

Imports a CSV formatted file into the specified APPX file.

.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 SET SPECS

Sets the file specifications

.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.

Role Based Security Routines

The Role Based Security routines provide a way for you to add RBS maintenance capabilities to your applications. This can be useful if you want your users to maintain RBS but do not want to give them full System Administrator access.

.RBS HIERARCHY MTCE

Invokes the 'Security Hierarchy Maintenance' program, bypassing the System Administrator requirement (System Administration -> Role Based Security -> Security Hierarchy Maintenance).

.RBS PROCESS SECURITY

Allows the designer to invoke ' Access Control List - Processes' for a particular parent / child pair (System Administration -> Role Based Security -> Access Control List - Processes).

.RBS REGEN

Rebuilds the internal RBS cross reference file for the selected apps.

.RBS UPDATE SECACL

Allows the designer to update the RBS Access Control file directly.

Data API Subroutines

These subroutines are only useful when working with the Data API in Release 5.5.0 and higher.

.DATA DEBUG LOG

Use this subroutine to write a free format message to the debug log.

.DATA WRITE STREAM

Use this to return results to the caller.

.DATA GET PARAM VALUE

Use this to get the value of a parameter from the URL.

.DATA BAD REQUEST

Use this to return a free format error message to the caller.

-- JeanNeron - 2013-05-28